be common-readme compatible

[hackergrrl]

It would be really cool if the output of of standard-readme-generator was compatible with common-readme. Since common-readme doesn't impose much, the only real thing to get consistent between the two is the notion of cognitive funneling:

Start with the most general information at the top (Name, Description, Examples) and if the reader maintains interest, narrow down to specifics (API, Installation). This makes it easy for readers to "short circuit" and continue the hunt for the right module elsewhere without wasting time delving into unnecessary details.

I think standard-readme would only need a couple of tweaks, though these are of course all personal preferences that are biased toward small modules (in any ecosystem):

1. Consider making the TOC optional, only because it introduces a lot of visual interference for people scanning the readme. It can easily add an extra pageful or two if all children sections are present. If a user does opt in for one, consider maybe only showing top-level items.
2. Consider pushing Installation under API. This is on the premise that a user is unlikely to consider installing a program unless they've looked at it in some detail, which generally includes a perusal of its usage and its API.

Cool! I think everything else is pretty much compatible and fits just fine 🎉

[RichardLitt]

Thanks, @noffle! I think that I can match common-readme for cognitive funneling.

Regarding your points:

1. I am going to make the ToC required. It is very helpful to know, at a glance, what is there; I don't think that having them reduces cognitive load, and I think that having one can greatly reduce the need to scan an entire repo. However, to make it easier, I'm adding a requirement that it only grabs the ## headings by default - third and fourth level are optional. I think this matches your requirements.
2. I do not want to put Installation under API. API is too language and js specific, I think. From my experience, when I go to a readme, I actually want to install it before reading - this is because the README is actually not the first time you interact with a module. You find modules through code or through your social network - the README should describe a module so that any differences in background knowledge are leveled out. Someone with no experience should get it, someone with a ton of experience but needing specific questions should find them answered. For me, most of the time, I want to know about installation just after reading the description, and not while I am perusing the API.

What do you think?

[hackergrrl]

On 05/26 07:32, Richard Littauer wrote:

Thanks, @noffle! I think that I can match common-readme for cognitive funneling.

\o/

1. I am going to make the ToC required. It is very helpful to know, at a glance, what is there; I don't think that having them reduces cognitive load, and I think that having one can greatly reduce the need to scan an entire repo. However, to make it easier, I'm adding a requirement that it only grabs the ## headings by default - third and fourth level are optional. I think this matches your requirements.

Awesome -- that's fair.

1. I do not want to put Installation under API. API is too language and js specific, I think. From my experience, when I go to a readme, I actually want to install it before reading - this is because the README is actually not the first time you interact with a module. You find modules through code or through your social network - the README should describe a module so that any differences in background knowledge are leveled out. Someone with no experience should get it, someone with a ton of experience but needing specific questions should find them answered. For me, most of the time, I want to know about installation just after reading the description, and not while I am perusing the API.

Yes, that's fine; your logic makes sense.

To better explain my angle: my preference for Installation after is because I prefer to evaluate the API /really carefully/ before installing a module. To me, the API is probably the biggest decider of whether I'll use the module or not -- even if it does what I want. A poor API is often enough to warrant writing the module over again. However, I recogonize that my experience is not the rest of the world's. I'm happy with Installation coming first. :)

[RichardLitt]

Great. :) Ok! I think this is settled. Thanks so much for talking me through this.

[hackergrrl]

Hey Richard! Thought this might be a fun read for you: https://github.com/noffle/art-of-readme

[RichardLitt]

Saw it already. :) Looks good, will PR some writing stuff if you'd like. Would love to get a mention of Standard Readme; although we disagree on the place of the Install section, we come from the same place.

[hackergrrl]

Awesome! Thanks for giving it a read.

Standard Readme mention: absolutely! I think a See Also or References section would be useful. PR me and I'll merge it in. ❤️