Suggestion: prohibit “Install” and “Usage” for doc modules instead of leaving them optional

[wooorm]

Currently both Install and Usage are “required by default, optional for doc modules”.

This also brings up the question: what are doc modules? The term is used only in these two lines. Should there be a definition somewhere on what is and isn’t a doc module?

If that’s answered: maybe these sections can be required for non-doc modules and prohibit for doc modules?

[RichardLitt]

A documentation module is a repository that does not have functional code. An example would be https://github.com/RichardLitt/knowledge.

We should define it.

Why prohibited over optional?

[wooorm]

Thanks for the definition!

I dunno, I don’t think doc modules per that definition could ever have an “Install” or “Usage” section (or “API” for that matter). And in that case we’re in the “extra sections” supersection.

---

Now that I think about it: There’s also other types of repositories: repo’s for books, websites, demos, or courses. These all have hugely different requirements for titles and sections. One could argue only the intro (“Title” through “Long description”) is needed for those. And “License”.

For example, Maintainer(s) and Contribute are both requires by standard-readme, but not present in RichardLitt/knowledge (which I get)

I feel that trying to support non-code READMEs makes it harder to spec things: everything’s optional. Maybe we should define standard-readme as a spec for code-only projects?

[RichardLitt]

I think that standard-readme should work for other projects, including the ones you mention. Other sections can exist, and we have a place for them in the standard. But title, badges, description, contribute, license - these should all exist, in every readme.

I think prohibited is more likely to end up with an edge case where it is needed, and it can't agree. Optional is a bit looser, and I think that's OK.

[wooorm]

Makes sense!

Would it in that case make sense to differentiate project, defining “presets” of headings needed for code, docs, books, websites, etc?

[RichardLitt]

I'm not sure the benefit would outweigh the costs, there. I think leaving a flexible default for non-code does the trick needed. Good thinking, though!

[wooorm]

I’m thinking from the linter perspective, the outline is very free, so there isn’t much to warn for related to the order of things, a “preset” passed to the linter or inferred would allow for more things to check!

[RichardLitt]

I'm not sure it is all that free. I could code up a checker quickly, if you like, to see how the logic works? Perhaps I am misunderstanding how I laid it out.

[RichardLitt]

Or: @wooorm, do you have a checker somewhere atm? Can you point me to it?

[wooorm]

This was related to some thinking I jotted down here: RichardLitt/standard-readme-preset#4 (comment)