A good README

Posted on

Creating a documentation for a project is a well known good practice but many developers tends overlook it or at least tend to be a bit lazy (the source code says everything you need to know). Nevertheless, whatever the target a documentation is always a good thing to do and I wouldn’t recommend enough to write along the way rather than at the end of the project.

Whatever the size of the project, the first thing to do begin with is the README file. That’s the minimum you should do (at least what I do) and, even if there is no standard way of writing it, there is a common understanding of some parts it should contain.

  • Description of the project
  • Installation
  • Usage
  • Development setup
  • Contribution
  • License

If you have other relevant things to add (such as known bugs for example), you can but I would recommend in some cases to keep the README concise and link to a more detailed documentation such as a ChangeLog or troubleshooting unless you see it fit. Giving an example wouldn’t help much because there are plenty that fits the bill out there but let me help you by giving you some examples: David Larlet template, Dan Bader blog post. Nevertheless I would mention two other things. The first is about the language used to write it. Many people recommend to use Markdown, which is good but using reStructuredText is a pretty good candidate as well. However more complex to apprehend, it is very good to use and is a bit more powerful than Markdown. The first obvious thing is that if you use Sphinx to generate your documentation, you can include any file you want in your documentation (including README and so on) and avoid duplication of content. Moreover, you can as well find very interesting plugins to integrate a bibtex file (very useful for scientific citations) or a glossary. I’ve been using it more and more over the past last months and I found it very useful. Finally, the last thing is about README Driven Development (RDD). Writing the README file usage of your application or API before hand is I think very interesting and very useful because it makes you think about the usage beforehand and can sometimes avoid to write very complex API that are driven by the development process rather than the usage of it. I would recommend anyone to have a look into that, there is nothing complex or very strict process to apply just some interesting way of thinking (Slides from OncleTom.io, Blog post from Elliot Chance and the root article from Preston Werner).