search

zcei / standard-readme

:star2: README Standard Style — One Style to Rule Them All
MIT License
57 stars 3 forks source link

tiny npm package #5

Closed fibo closed 5 years ago

fibo commented 8 years ago

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.

Tiny npm package.

zcei commented 8 years ago

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?

fibo commented 8 years ago

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.

zcei commented 8 years ago

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)

zcei commented 8 years ago

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)

fibo commented 8 years ago

Actually I was thinking about this topic, thank you for showing me the issue. I added this comment https://github.com/zcei/standard-readme/issues/3#issuecomment-172575973