post about READMEs

[maelle]

• Some text about a README is often an entry point to the package. take-home message would be one should prepare a nice README. How: read other READMEs, have someone else read the README.

• this quote https://twitter.com/ma_salmon/status/1151779026702352384

• sample of top and trending packages (pkgsearch), with a GitHub repo URL, for which we can find a README (via GitHub's preferred README API endpoint) -- so a limited sample. On this sample, look at

  • how many READMEs use the package name as first header
  • how many READMEs have an install(ation) section
  • look at most used section titles over all READMEs
  • display the structure of a few READMEs
  • distribution of the number of level 2 headers?

• Mention usethis' README template.

• Link to the Write the docs newsletter about READMEs

• Link to https://www.garrickadenbuie.com/blog/dry-vignette-and-readme/ and roxygen2 documentation tags article, to explain how to re-use stuff.

• https://github.com/ropensci/software-review-meta/issues/55

• https://devguide.ropensci.org/building.html#readme

[maelle]

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]

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

[maelle]

Post title = "WRITEME"?

[maelle]

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

[maelle]

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]

Suggests a few pitch structures based on examples?

• the usethis "the goal of blabla is to"
• a question, an answer
• ...

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

[maelle]

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

[maelle]

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

[maelle]

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)