be common-readme compatible about standard-readme HOT 6 CLOSED

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?

from standard-readme.

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. :)

from standard-readme.

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

from standard-readme.

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

from standard-readme.

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.

from standard-readme.

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. ❤️

from standard-readme.