A readable README file at Write the Docs NA 2016
This week I’m attending Write the Docs NA 2016. These are my notes on a session by Daniel Beck, titled “Write the readable README”. All credit goes to Daniel, any mistakes are my own.
Daniel Beck writes tech docs for developers and sys admins. A lot of his work is in deployment guides. In the course of his work, Daniel comes across many README files. In self defence, he decided to research README files, and looked at more than 200 of them. He analysed them from the following points of view:
- The type of project the README documents
- Other files accompanying the README file
- The markup used in the README
- The topics covered
- Links to other files and documents
- Images in the file: logos, other visual aspects
- What was good and effective
- What was bad or not helpful
- How did the README make him feel?
Daniel found that README files vary in quality. Some of them are even hostile to the reader. Some of them miss vital information, such as project name or location of the project. Some READMEs are very old – the oldest one dates from 1974! Typically, they’re Markdown files that contain a lot of information in visually unappealing form.
Tools like GitHub and Bitbucket have brought README files back to life.
The best READMEs give you confidence about a project. They help the reader identify and evaluate the project. They help you get started (use the project at least once) and engage with the project.
So, README files are useful, and are something we’ll probably need to create. Daniel cautioned us against relying too heavily on templates for README files, as a template may make you think that you’ve included everything you need even though there are some gaps.
Instead, Daniel has prepared a README checklist, available on GitHub. It’s a useful document, in that it suggests parts you may need in your README file, and also describes what to put in each part, tips on how to find the content for that part, and guidance on when you may need the part. Daniel also pointed out the template for contributing guides for open source projects.
Thanks Daniel for an entertaining and instructive talk, and for a useful checklist!