Readme based development

Original author: Tom Preston-Werner
  • Transfer
Lately, I hear a lot of talk about test-based development (TDD), function-based development (BDD), extreme programming (XP), SCRUM, standing meetings, and God knows how many techniques for creating software, but all these techniques do not make sense if the software that we create does not meet the requirements of users. Let me try to explain it differently. An ideal implementation of a malformed specification is useless. Just as the usefulness of a beautifully written library tends to zero if it has no documentation. Something is definitely wrong if your application does not solve the problem or if no one knows how to use it.

Wow. So how do we solve this problem? Simpler than you think, and important enough to highlight the answer in a separate paragraph.

First, create a Readme file.

That's right - the first thing. That is, even before you start writing code or tests or functioning or user stories or anything else. I know, I know, we are developers, and not, damn it, technical writers! But here you are mistaken. Writing a Readme is an essential part of writing a good program. Until you can write your point in writing, you still cannot start writing code. Something was lost between the Great Crusade Against the Waterfall Type of Development Process and the Universal Acceptance of Flexible Development Methodologies. Don't get me wrong: the waterfall type of development process is way too far. Large systems, described to the smallest detail, end their existence with incorrect systems, described to the smallest detail. We were right when we decided to go against it. But that, which has taken the place of the waterfall type development process, another extreme. Now we are faced with projects with a minimum of poorly written documentation or in general with its absence. Some projects do not even have a Readme file!

This is unacceptable. There must be a middle ground between the piles of technical specification papers and its absence, as such. And actually it is. This middle ground is an inconspicuous and modest Readme file.

It is important to distinguish readme-based development from document-based development (DDD). The technique of developing based on Readme can, in principle, be considered as a subclass or incomplete version of development based on documentation. By limiting your design documentation to just one file, which is also intended to be a file that introduces another person to your program, the Readme-based development methodology protects you from a waterfall syndrome that a document-based development methodology can turn into, punishing you for being too long or saturating the specification with detail, while rewarding you with keeping the libraries small and modular. These simple rules will go all the way along with your project, leading it in the right direction, but without unnecessary processes,

Starting with writing a Readme file at the very beginning, you create a number of significant advantages for yourself:
  • The most important thing is that you give yourself the opportunity to think about the project, without having to change the code every time it comes to your mind to do something different or, for example, choose what will happen in the Public API. Remember the feeling when you first started writing automated tests for code, and realized that you caught all the possible types of errors that, otherwise, could sneak into your code base? This is the same feeling you will experience if you write a Readme file for your project before you start writing code directly.
  • And also, you will immediately have wonderful documentation at hand, as a by-product of writing a Readme file in order to determine what you want to implement. And you will see that writing this document is much easier and more pleasant when you just started the project and your excitement and motivation are at their maximum. Writing a Readme retroactively is pretty darn boring, and you will definitely miss some important details if you do so.
  • You will get even more benefit from your Readme file if you work in a team. If everyone in the team has access to this information before you finish writing your code, they can confidently begin work on their projects that will interact with your code. Otherwise, if the interaction interface is not defined, you will either have to write the code sequentially, or you will encounter the possibility of rewriting a large part of the code.
  • It is much easier to conduct a discussion based on something recorded. If nothing is described, you can endlessly discuss the problem circle after circle repeating the same thing. Such a simple action as recording a proposed solution means that everyone has a specific idea that can be challenged and repeated later.

Consider the process of writing a Readme file for your project a true act of creation. This is exactly the place where all your brilliant ideas should be expressed. This document should occupy a separate place, as evidence of your creativity and self-expression. The readme file should be the most important document in your code base; and it’s right to create it very first.

Notes:
  1. Translations of software development technician names are taken from here .
  2. On the principles of development through the documentation described in the speech Corey Oordt on PyCon 2011


Also popular now: