READMEs

[maelle]

Topic

How to write clear and compelling READMEs.

Who is the audience?

Package developers
Maybe people interested in starting to contributed: docs are a good way to start and as an outsider you might write a better pitch for the package?

Why is this important?

I often read READMEs that could be improved and every package needs one, especially since the pitch that the README is can be re-used elsewhere.
Most potential users of a package have very little time so if the README loses them they won't try to use the package, or they'll lose time using a package that's not adapted to their needs (because the README was misleading).
It's also a topic closely related to "writing a good pre-submission inquiry".

What should be covered?

What's a good README, how to write one, who can give you feedback on it.
Also some tricks specific to R (usethis' README template, re-use of sections for the vignette).

Suggested speakers or contributors

• one of the editors or a reviewer who reviewed several packages could explain how they read READMEs.

Resources you would recommend to the audience

https://www.writethedocs.org/blog/newsletter-july-2019/#readmes-on-readmes-and-other-readme-related-resources
the discussion started by @noamross in ropensci/software-review-meta#55

[maelle]

I'm planning a R-hub blog post about the topic. r-hub/blog#29

[stefaniebutland]

Content copied to new issue #21 (comment). Closing this issue.