Meet by README – what you need to know about the documentation
Reducing the time spent searching for information is a task that is talked about unforgivably little. This task must be solved by individual developers and, in general, by companies. For example, CloudMTS provides materials to help users get up and running quickly and successfully in the cloud. A knowledge base with which you can independently study cloud services is a good help for a hassle-free migration.
Taking the analogy further, getting to know a new development can simplify the README file, a basic component of documentation.
Should developers write documentation? As often happens, there is no clear answer to this question.
Today we’ll talk about tools for building and working with README, and also discuss the topic of documentation.
Documentation dilemma
Probably the most common opinion is that every self-respecting programmer is obliged to document his own code, including fairly obvious points, the nuances of which can be missed if you do not return to what you wrote for a long time.
At the same time, colleagues and, perhaps, even outside developers who do not have the opportunity to “get inside” the author’s head can interact with the code base. In addition, the author of the code may leave the company altogether, and then understanding the program will become even more difficult.
All these factors can limit the team’s room for maneuver at the most inopportune moment. If we are talking about open source, then without high-quality explanations it is difficult to attract new participants to the development of the project – it will also be more difficult for them to understand the code and principles of the application.
Some developers are so convinced of the need to create documentation that they make working with it an absolute priority, practicing the Documentation First approach. In this case, documents begin to be prepared even before the first line of code is written.
At the same time, there is a parallel opinion that working with documentation should not concern a programmer. It's one thing to prepare compact but comprehensive code comments. Completely different – Software Requirement Specification (SRS) – special documentation for software that contains information about how the system should behave, what functions it should perform, what load it should withstand, etc.
This is a task for technical writers who are more familiar with edge cases and anti-patterns and are therefore able to describe them in more detail.
In addition, we often exaggerate our ability to express our thoughts accurately and clearly for others.
Psychologists from Stanford University conducted an experiment: the participant had to tap a popular song on a table with his fingers so that another person would guess it.
What do you think is the probability of guessing the song correctly?
Only 2.5%.
How likely do you think the participants think listeners are to guess the tune?
50%.
Adam Grant, a psychologist and one of the most popular TED speakers, writes in his book Originals: How Non-Conformists Move the World that your ideas become too obvious to you. You live with them for a long time, they are tightly integrated into your picture of the world, and therefore it seems to you that other people will easily notice the obvious. As a result, people convey to others many times less than they could and what the audience needs to understand.
What does this have to do with writing good documentation?
Documentation becomes incomplete because it assumes a lot of knowledge on the part of the reader.
The person who comes to document the code from the outside, from the “user's” point of view, will make sure that no steps are missed in the manual.
Interestingly, some experts consider it a waste of time to write not only documentation, but also comments to complex code. Writing is a complex and demanding task that requires clear organization of thoughts, critical examination and clear expression. A common mistake is to assume that authors of obscure code will somehow be able to express themselves clearly in comments.
IEEE panel member Kevlin Henney argues that writing compact but comprehensive explanations is not easy, so a developer can get away with not commenting if he writes clean, understandable code.
An illustration of this approach can be the concept “competent programming“, proposed by Donald Knuth. It states that the syntax of algorithms should resemble natural language.
Another approach used in practice is “self-documenting code“(self-documenting code). In this case, programmers adhere to established standards for structuring code – this makes it easier to understand within work processes.
About README files
There is an issue on which there is not much disagreement among developers. It addresses the need to write quality README files to quickly become familiar with the software. They typically contain a brief overview of the project's goals, installation instructions, known issues, and, in most cases, a quick start guide for those new to the program.
As if to emphasize the importance of README files, some people practice Readme Driven Development (similar to Documentation Driven Development). Interestingly, Tom Preston-Werner, the founder of GitHub, is among his followers. In his opinion, working on the information file allows you to think through the logic and nuances of the project in advance, but does not greatly slow down the development process.
An example of a comprehensive README file is the document gollum (wiki system built on Git). The project page is moderately detailed and well structured: there are sections with a description, system requirements, installation guide, configurations and information for potential sponsors.
The authors took a step towards an easy-to-read wiki format. To quickly create similar readme files, you can use a variety of tools and even seek help from the community.
README Templates
There are templates that help create the basic “skeleton” of a README. An example would be open source
which is distributed under the MIT license.
The Standard Readme consists of a specification and a file generator. Specification includes includes recommendations for writing information files. Thus, the author considers sections that include the name of the software, a brief description, installation and licensing information to be mandatory. Blocks on working with APIs and information security issues may be optional. Instructions are attached to each of the subsections – what the volume should be, what tools to use, how to insert links and code examples.
As for the Standard Readme generator, it helps fill out the file according to the standard described above – installation requires Node.js, a package manager npm and utility Yeoman.
And there are quite a lot of similar generators on the market, including more complex ones. So, Amazing GitHub Template (MIT License) in addition to the README allows you to generate license files and Code of Conduct documentation. You can generate them in two ways – using the utility Cookiecutter (BSD 3-Clause), which will allow enter data in semi-automatic mode, or manually according to a template.
Using such tools, you can generate any README file in a few minutes. The main thing is not to overdo it with the design. Complex markup can make it difficult to understand, so it is important to maintain a balance between meaning and form.
Web builders README
Another type of tool is online README editors. One of the most developed projects in this direction can be called
. The application is free (sources are posted on
), works directly in the browser, it has a convenient interface with drag-and-drop support – the main sections of the README are presented in the form of blocks, from which you can assemble the final document like a constructor. As you drag and drop, these building blocks are automatically populated with template data that you can use as an example.
Another project worth mentioning is Make a README (MIT License). It already contains standard blocks with template data in Markdown format. All changes made are immediately displayed in a separate window. You can immediately see how the corresponding README file will look on GitHub.
There are also less specialized web tools such as StackEdit. The application is distributed under the Apache license and allows you to create any template using Markdown markup, as well as using a WYSIWYG editor. With its help, you can create not only README, but also other documents. In addition, the tool allows collaboration – several people can simultaneously edit a file and leave comments on it.
Platforms for feedback
In general, the IT community welcomes such projects, as they simplify the preparation of basic documentation and partially automate the process. But it happens that open tools only support one file format – for example, MD – and specialists lack other options (org, info, txt, etc.).
A special category of tools are platforms and forums where enthusiasts help create and evaluate README files. One such project on GitHub is Feedmereadmes. Its purpose is to create an environment where help and feedback can be obtained in compiling information files.
The work of the site is structured as follows: users send their README to the Issues section of the repository and wait for feedback from their colleagues. A new review request appears there approximately every two weeks. According to the authors, Feedmereadmes may be of interest to developers who find it difficult to write documentation; technical writers who want to contribute to open source; and product managers who are ready to share their expertise in product development.
There are specialists who do README checking as a hobby. But the problem with such platforms is that feedback is not always given. Requests often go unanswered, since everything depends on the community’s desire to participate in the exchange of experiences and motivation of community members.
