Readme based development
Recently, I have heard a lot of talk about testing-based development (TDD), development-based development (BDD), extreme programming (XP), SCRUM, standing meetings, and God knows how many techniques for software creation, but all these techniques do not make sense if the software we create does not meet the requirements of users. Let me try to explain it differently. The ideal implementation of an incorrectly written specification is useless. Just as the utility of a beautifully written library tends to zero if it does not have documentation. Something is definitely wrong if your application does not solve the problem posed or if no one knows how to use it.
Great. And how do we solve this problem? Easier than you think, and important enough to highlight the answer in a separate paragraph.
First, create a readme file.
That is - 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 the Readme is an integral part of writing a good program. Until you can put your thoughts in writing, you still can’t start writing code. Something was lost between the Great Crusade Against the Waterfall Type Development Process and the General Recognition of Flexible Development Methodologies. Don't misunderstand me: the waterfall type of the development process goes too far over a stick. Large systems, described to the smallest details, end their existence with the wrong systems, described to the smallest details. We were right when we decided to go against it. But what took the place of the waterfall type of the development process is another extreme. Now we are faced with projects with a minimum of poorly written documentation or even with its absence. Some projects don't even have a readme file!
')
This is unacceptable. There must be a middle ground between piles of technical specifications and its absence, as such. And in fact it is. This golden mean is an inconspicuous and modest Readme file.
It is important to distinguish the development based on the Readme from the development based on the documentation (DDD). The development methodology based on the Readme can, in principle, be considered as a subclass or an incomplete version of the 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 development method based on the Readme protects you from the waterfall syndrome which can develop a documentation methodology, punishing you too long replete with the specification, and at the same time 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 aimed at controlling that you are doing everything as it should.
Starting with writing the Readme file at the very beginning, you create for yourself a number of significant advantages:
Consider the process of writing the Readme file for your project as 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 creative abilities and self-expression. Readme file should be the most important document in your code base; and it is right to create it the very first.
Notes:
Great. And how do we solve this problem? Easier than you think, and important enough to highlight the answer in a separate paragraph.
First, create a readme file.
That is - 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 the Readme is an integral part of writing a good program. Until you can put your thoughts in writing, you still can’t start writing code. Something was lost between the Great Crusade Against the Waterfall Type Development Process and the General Recognition of Flexible Development Methodologies. Don't misunderstand me: the waterfall type of the development process goes too far over a stick. Large systems, described to the smallest details, end their existence with the wrong systems, described to the smallest details. We were right when we decided to go against it. But what took the place of the waterfall type of the development process is another extreme. Now we are faced with projects with a minimum of poorly written documentation or even with its absence. Some projects don't even have a readme file!
')
This is unacceptable. There must be a middle ground between piles of technical specifications and its absence, as such. And in fact it is. This golden mean is an inconspicuous and modest Readme file.
It is important to distinguish the development based on the Readme from the development based on the documentation (DDD). The development methodology based on the Readme can, in principle, be considered as a subclass or an incomplete version of the 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 development method based on the Readme protects you from the waterfall syndrome which can develop a documentation methodology, punishing you too long replete with the specification, and at the same time 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 aimed at controlling that you are doing everything as it should.
Starting with writing the Readme file at the very beginning, you create for yourself a number of significant advantages:
- The most important thing is that you give yourself the opportunity to think about the project, without having to change the code every time you come to mind to do something differently or, for example, choose what will be in the Public API. Remember that feeling when you first started writing automated tests for code, and realized that you caught all possible types of errors that, if not, 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 the code directly.
- And yet, you will immediately have excellent documentation at hand, as a byproduct of writing the 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 have just started the project and your excitement and motivation are at their maximum. Writing the Readme in retrospect is damn boring and you’ll definitely miss some important details if you do.
- 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 working on their projects that will interact with your code. Otherwise, if the interaction interface is not defined, you will have to either write the code sequentially, or face the possibility of rewriting a large part of the code.
- It is much easier to conduct a discussion based on something written. If nothing is described, one can endlessly discuss the problem round and round by repeating the same thing. Such a simple action, such as recording the proposed solution, means that everyone has a specific idea that can be challenged and repeated later.
Consider the process of writing the Readme file for your project as 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 creative abilities and self-expression. Readme file should be the most important document in your code base; and it is right to create it the very first.
Notes:
- Translations of software development technician names are taken from here .
- The principles of development through documentation are described in a speech by Corey Oordt at PyCon 2011
Source: https://habr.com/ru/post/126747/
All Articles