tiny npm package
fibo opened this issue · comments
I wrote an article about this topic, it includes some guidelines to create a README.md: it goes further, since it includes also tools (like standardjs) and conventions to create a minimal but maintainable package.
I would like to adopt a standard for a README, we could discuss here to make converge our ideas.
Hej,
I wanted to revive this project for the last couple month, but never got my hands dirty again.
So I'm happy you're jumping on the train!
Still, I wouldn't introduce tools into a standard, that merely describes how a decent readme should look like. (Just because someone is using semicolons in their code, they can still write standard-readme compliant readmes)
What I would like to introduce are more rules for defining your API.
Currently I'm thinking about default sections like Command Line and API, where you have a unified style of describing your package.
For every other section, its layout wouldn't be checked.
Is there anything else you'd like to see baked into standard-readme?
A License section is missing.
The API section could look like https://github.com/mafintosh/multicast-dns#api
Also a Description section is a good idea.
Some section could be optional, for example: CLI.
Please see #4 for the current issues with the License section.
Do agree, that one is needed (currently opting for a small License section linking to a LICENSE file)
Some section could be optional, for example: CLI.
Yes, they may be left out - I want to have a linter tool in the end that tells you if you leave out important sections (for example neither Command Line nor API is used, I would at least warn)
Also a Description section is a good idea.
That's what the description part right under the package name is for.
If you do need a more extensive reasoning about your package, one can feel free to use a "optional block" for it.
The API section could look like
It could basically look like anything.. That's why the discussion has an own issue (#3), I'd love to get your input there (at best with arguments, why this style is superior to the other proposed ones)
Actually I was thinking about this topic, thank you for showing me the issue. I added this comment #3 (comment)