Data nerd and test driven development (TDD) enthusiast, Elliot Chance has recently published an article in which he claims that each time you start a software development project, be this your pet project or client's custom project, you should aim to deliver a clean and understandable code that can be re-used by other developers (who'll be working on your project if / after you leave it). While each developer has own opinion about best practices and tools that should be used in each particular project case, a README document is something that should be used unanimously on your project to make sure you don't lose sight of the project and its future milestones.
Readme is the most important file on your project documentation, according to Elliot. This file should contain a short summary of all project tasks and goals, configuration guidelines, log of known / expected issues and a detailed description of what needs being done to get the project started and ramp it up. But don't get it wrong - Readme isn't all documentation you may need for your project development. Yet, you can really be surprised to find out that a humble Readme document actually covers most of issues and questions that are likely to be asked by others involved in your project.
If you create your Readme document prior to the project's kickoff (coding), you'll enjoy the following benefits when the project is in progress.
- You'll have a bird's eye view of what functionality needs to be deployed and how open APIs can help you do it. At this point, making changes to software architecture is super easy before any code has been written.
- Once you start coding, Readme will help you keep the focus on what needs to be delivered and how exactly you should do this.
- It can show you and your project team how much progress is happening while the project is being in progress.
- It's much easier to discuss things written down on paper than those taken out of the blue. Rather than holding hundreds of useless meetings that only steal developers' time and lead to nowhere, you can make changes right to your Readme and reflect them further in specification. Having a single document (in version control) is a perfect way of communicating changes as they occur. Also, recording every single change as you go is much more effective than remembering them all afterwards (which is nearly impossible!).
At Intersog, we follow Readme Driven Development (RDD) on all clients' projects, because we believe in the power of a Readme file. However, I've reached out to my fellow Quorans to find out what they think about RDD and whether they create README docs on their projects.
Juno Vepsäläinen, Author of SurviveJS - Webpack and React:
"It depends entirely on the type of the project. Writing documentation first can be valuable as it forces you to think about the API from the user point of view. Ideally you should be able to run the README code against your project to test it and make sure the code actually works.
A well written README also serves the purpose of marketing. Written effectively it makes it easier to adopt your solution. It will also serve you at the maintenance phase when you need to get back to the project at a later time. You’ll thank yourself for writing good documentation then.
Sometimes a README can be an afterthought. At minimum I like to provide a basic description, minimal API, and licensing information. On larger projects I push a lot of the information elsewhere and use the README for describing the project on a high level so it’s easy to get started with it."
Arsalan Wahid Asghar, Software Engineer:
"A Readme document is one of the most important aspects of any product may it be software or not. A readme document usually answers the following questions :
- What are the features of this software?
- Who is this software for?
- How to install the software?
- How to use the software?
- Does this software have any limitations?
- What type of license is associated with the software?
Any many more…
If you add even some of these details to the Readme document in the beginning or during development it will not only create transparency between the future user and the software as to why the product is suitable for them, but give a clearer picture to the dev team as well as to what goal is set for the final product in the feature list."
"I almost always create a Readme, even for internal, private projects, with a minimum of:
- Basic install instructions
- Basic build and operation/usage instructions
- If relevant, basic test instructions
API docs are typically embedded in the source (Doxygen or JSDoc) and for libraries would be built as part of the building instructions.
These are things that anyone, including myself, who picks up the project in the future, would need to know."
To conclude with, do others a favour and create a Readme document before you start coding. Someone down the years will really thank you for this!