r-hub / blog

The R-hub blog
https://blog.r-hub.io/
11 stars 12 forks source link

post about READMEs #29

Closed maelle closed 4 years ago

maelle commented 4 years ago
maelle commented 4 years ago

Count words in the sample, to use Miles' "If a README can give the whole package overview and be read in under 5 minutes (1250 words) maybe it's fine?".

maelle commented 4 years ago

Also look whether there is a TOC because @gaborcsardi said a longer README with a TOC is fine. :wink:

maelle commented 4 years ago

Post title = "WRITEME"?

maelle commented 4 years ago

Maybe I'll count words for text, and lines of code for code blocks.

maelle commented 4 years ago

Mention actual re-use of parts but also re-use of the way of pitching. When writing the README you have to find a compelling way to describe your package, and that is something you can re-use in other forums (package docs, talks, tweets etc.) so time invested in a good pitch for the README is really not lost.

maelle commented 4 years ago

Suggests a few pitch structures based on examples?

maybe also mention the repo description/Package Title but that is probably beyond the scope of the post.

maelle commented 4 years ago

TODO: fix symlink handling (e.g. rversions README).

maelle commented 4 years ago

For Hugo the estimated reading time is 220 words / minute.

maelle commented 4 years ago

add number of lines as a variable. (we have number of words in text, number of lines of R code, structure, but the overall length might be interesting)