Standard open source documentation
While this idea may seem silly, simplistic, and too general at first glance, I would like to suggest a standard way of documenting open source projects. I know that each project is individual and my idea has already made you smile, but I hope you will understand me if you read this small post.
We, the authors of the code, will save the standard from the need to come up with the documentation structure for the next project. It is much easier to fill in the gaps in a prepared structure than to think about it every time. And the simpler and faster it will happen - the more developers will create good documentation. (In the end, we will have more time for code and architecture - note. Lane.)
A standard format can also make documentation easier to understand if the reader is familiar with its structure. For most things, design is the best way to engage the consumer, and that is what design needs. So the desire to satisfy everyone often leads to the fact that no one is satisfied, this also applies to documentation. Despite the fact that it is worthwhile to apply a personal approach to learning, I believe that carefully thought-out and organized documentation will allow covering a larger percentage of potential users. An attempt to satisfy the wishes of all leads to excessive documentation: it is difficult to accompany such documentation and it frightens the reader.
')
In any case, this is only the first draft of the standard that I propose. Comments are welcome!
Documentation should be broken down into five parts. These parts do not necessarily have to be on the same page; moreover, it is most practical to place them on several sites (for example, automatically generated API help, “official” homepage, video tutorial, etc.). However, each section should contain links to any other section, to improve understanding and simplify access to different parts of the documentation.
The order of the parts must be regulated. Two of the parts I offer (IV and V) do not require a clear order, but in general it should be obvious to a beginner. No one should take the time to understand how to read the documentation.
In the following sections, I will often write as if I am not the author of the documentation, but her reader. I specifically do this so that you understand my point of view. It is usually difficult to think about the documentation of your project, so I suggest that you read the examples of the documentation that you yourself had to learn while reading. It seems to me obvious that the documentation should be developed on the basis of what is useful for the reader, and not on the basis of the simplicity of its writing.
Please note that at this stage I do not propose a formal section title, and I’m not sure whether specific titles should really be part of the standard.
This is a very important part that is usually forgotten. Often we draw our attention to software because we have heard the name somewhere, it seemed interesting to us and we want to understand whether it will be useful to us. We may not know:
All this information is extremely useful, and this is perhaps the most difficult part of the documentation that the developer must write. As authors, we know well what our code does. For this reason, it would be good to write this part of the documentation at the beginning of the development of your project, ideally before it starts. Of course, you will change it in the process of how to implement or add new functionality. You may even change your goals and priorities. But it is important that you lay the foundation at the moment when you yourself are new to your project. Once you know the details, it will be difficult to abstract from them.
In the case of free open source software, the download URL is often located in close proximity to the documentation, but no one knows if they will change in the future. So pretend to be writing a good old paper book without hyperlinks. Tell your readers:
After the software is installed, you will want to start using it, to do something simple to get an idea about it, its philosophy and accessible interface. It may not be exactly what you need, but if you can do something simple in five to ten minutes, you will feel confident. Make it so that your readers get it.
The three parts above are often found in the README file of the repository or source code archive. This is the first part, which is likely to be located elsewhere, as it may be large enough to read it sequentially at a time. To do this, it must be well indexed (at least contain a table of contents) and contain separate manuals arranged in order of increasing complexity. It’s hard to come up with abstract interesting examples, so start by describing how you use your product, or how you would like to use it. If you are asked “How to do ___?”, Add an answer to the question in this part of the documentation.
Finally, a good API reference is very important for large projects. If you are writing a plugin for RoR that contains two methods, then such help is probably not needed. However, your code should always be well commented, and when writing documentation, you should return to the code and put the comments in order in it. If you write the code in the same way as I do, you will be unpleasantly surprised how not informative are the descriptions of your methods.
Your thinking while writing code should be very different from how you think while writing documentation. As a rule, you should find that your comments in the code are too specific, that you consider many things to be obvious, which follow only from the context in which the method will be invoked. This is because when you write a method code, you are immersed in solving a particular problem, forgetting about other examples of use. Such thinking is necessary for writing code and is useless for explaining its meaning.
In short, when you are not writing code, go back to what has been written and add details in the comments to your methods so that the meaning of all the parameters is clear.
I have said this several times already, but I think it is worth repeating again: it is very difficult to explain your own code. An obvious solution to this problem is to write documentation to someone else. What I would like to see is a greater variety of contributions to the documentation of open source projects. The first reading of the project documentation is crucial for a new user. They are in a unique position, as they are not familiar with the project. That is why I strongly recommend that sections I, II and III be included in the repository of the project's source code, where they can be checked and edited by anyone. It is also a great way to cultivate the habit of people contributing to the open source projects they use. The first contribution is usually the most difficult, but many English language is not as scary as the source code.
What else to add about the ever-changing API? Is it true that quick changes result in comments or discussions being a better way to document a project than a single document? I probably spent more time reading blogs and other non-official documents than reading the official documentation of each open source project I worked with. Once I have read the official documentation, I can hardly return to it to find out what's new in it, because it seems so static ... I can re-read useful sections that I know about, but only if there is some indication that was added (since when? when was the last time I read this?). I’ll hardly be looking for documentation changes myself. This problem is beyond the scope of this article, but it is important to show the imperfection of this draft standard. This may mean that comments should be allowed on the documentation pages (in addition to the edits), or that we need to somehow quickly show the reader what's new (perhaps the edits should be styled as comments). The history of changes in the style of wiki-style, of course, will preserve the history of changes, but it seems to me necessary to more clearly present these changes.
We also need a way to specify the date and version of the software in the documentation. I think that the state of official documentation, as a rule, is so bad that we used to assume that what we read is already outdated. A mechanism for quickly marking a version of an item or section to indicate its compliance with the current software version would be very useful. (On the other hand, users may themselves mark sections or paragraphs as obsolete, but this does not solve the problem of presenting the relevance of documentation to new users). I think that official documents often become outdated precisely because it does not display the date of its update.
In any case, I hope that I have written enough to convince you of the possibility of creating and benefiting from the standard documentation for open source projects. Both software users and its authors will benefit from this. Please leave your comment and let me know what you think about this.
Motivation
We, the authors of the code, will save the standard from the need to come up with the documentation structure for the next project. It is much easier to fill in the gaps in a prepared structure than to think about it every time. And the simpler and faster it will happen - the more developers will create good documentation. (In the end, we will have more time for code and architecture - note. Lane.)
A standard format can also make documentation easier to understand if the reader is familiar with its structure. For most things, design is the best way to engage the consumer, and that is what design needs. So the desire to satisfy everyone often leads to the fact that no one is satisfied, this also applies to documentation. Despite the fact that it is worthwhile to apply a personal approach to learning, I believe that carefully thought-out and organized documentation will allow covering a larger percentage of potential users. An attempt to satisfy the wishes of all leads to excessive documentation: it is difficult to accompany such documentation and it frightens the reader.
')
In any case, this is only the first draft of the standard that I propose. Comments are welcome!
Standard (first draft)
Documentation should be broken down into five parts. These parts do not necessarily have to be on the same page; moreover, it is most practical to place them on several sites (for example, automatically generated API help, “official” homepage, video tutorial, etc.). However, each section should contain links to any other section, to improve understanding and simplify access to different parts of the documentation.
The order of the parts must be regulated. Two of the parts I offer (IV and V) do not require a clear order, but in general it should be obvious to a beginner. No one should take the time to understand how to read the documentation.
In the following sections, I will often write as if I am not the author of the documentation, but her reader. I specifically do this so that you understand my point of view. It is usually difficult to think about the documentation of your project, so I suggest that you read the examples of the documentation that you yourself had to learn while reading. It seems to me obvious that the documentation should be developed on the basis of what is useful for the reader, and not on the basis of the simplicity of its writing.
Please note that at this stage I do not propose a formal section title, and I’m not sure whether specific titles should really be part of the standard.
I. What it is and how it can be useful to you
This is a very important part that is usually forgotten. Often we draw our attention to software because we have heard the name somewhere, it seemed interesting to us and we want to understand whether it will be useful to us. We may not know:
- what tasks it solves
- how to make it work (environment, dependencies)
- his faults
- what it is not exactly intended for
- how does it compare with analogs
All this information is extremely useful, and this is perhaps the most difficult part of the documentation that the developer must write. As authors, we know well what our code does. For this reason, it would be good to write this part of the documentation at the beginning of the development of your project, ideally before it starts. Of course, you will change it in the process of how to implement or add new functionality. You may even change your goals and priorities. But it is important that you lay the foundation at the moment when you yourself are new to your project. Once you know the details, it will be difficult to abstract from them.
Ii. How to download / buy, install and configure
In the case of free open source software, the download URL is often located in close proximity to the documentation, but no one knows if they will change in the future. So pretend to be writing a good old paper book without hyperlinks. Tell your readers:
- how to get the software (download URL, commands to install using the package manager)
- how to install it (or you must specify a list of supported platforms)
- what are the main configuration options
- How to make sure that the software is installed and working correctly
- major problems that may occur during installation
Iii. How to start using it (tutorial)
After the software is installed, you will want to start using it, to do something simple to get an idea about it, its philosophy and accessible interface. It may not be exactly what you need, but if you can do something simple in five to ten minutes, you will feel confident. Make it so that your readers get it.
Iv. How to make more complex things (case studies)
The three parts above are often found in the README file of the repository or source code archive. This is the first part, which is likely to be located elsewhere, as it may be large enough to read it sequentially at a time. To do this, it must be well indexed (at least contain a table of contents) and contain separate manuals arranged in order of increasing complexity. It’s hard to come up with abstract interesting examples, so start by describing how you use your product, or how you would like to use it. If you are asked “How to do ___?”, Add an answer to the question in this part of the documentation.
V. API Help (auto-generated)
Finally, a good API reference is very important for large projects. If you are writing a plugin for RoR that contains two methods, then such help is probably not needed. However, your code should always be well commented, and when writing documentation, you should return to the code and put the comments in order in it. If you write the code in the same way as I do, you will be unpleasantly surprised how not informative are the descriptions of your methods.
Your thinking while writing code should be very different from how you think while writing documentation. As a rule, you should find that your comments in the code are too specific, that you consider many things to be obvious, which follow only from the context in which the method will be invoked. This is because when you write a method code, you are immersed in solving a particular problem, forgetting about other examples of use. Such thinking is necessary for writing code and is useless for explaining its meaning.
In short, when you are not writing code, go back to what has been written and add details in the comments to your methods so that the meaning of all the parameters is clear.
Questions, problems and ideas
I have said this several times already, but I think it is worth repeating again: it is very difficult to explain your own code. An obvious solution to this problem is to write documentation to someone else. What I would like to see is a greater variety of contributions to the documentation of open source projects. The first reading of the project documentation is crucial for a new user. They are in a unique position, as they are not familiar with the project. That is why I strongly recommend that sections I, II and III be included in the repository of the project's source code, where they can be checked and edited by anyone. It is also a great way to cultivate the habit of people contributing to the open source projects they use. The first contribution is usually the most difficult, but many English language is not as scary as the source code.
What else to add about the ever-changing API? Is it true that quick changes result in comments or discussions being a better way to document a project than a single document? I probably spent more time reading blogs and other non-official documents than reading the official documentation of each open source project I worked with. Once I have read the official documentation, I can hardly return to it to find out what's new in it, because it seems so static ... I can re-read useful sections that I know about, but only if there is some indication that was added (since when? when was the last time I read this?). I’ll hardly be looking for documentation changes myself. This problem is beyond the scope of this article, but it is important to show the imperfection of this draft standard. This may mean that comments should be allowed on the documentation pages (in addition to the edits), or that we need to somehow quickly show the reader what's new (perhaps the edits should be styled as comments). The history of changes in the style of wiki-style, of course, will preserve the history of changes, but it seems to me necessary to more clearly present these changes.
We also need a way to specify the date and version of the software in the documentation. I think that the state of official documentation, as a rule, is so bad that we used to assume that what we read is already outdated. A mechanism for quickly marking a version of an item or section to indicate its compliance with the current software version would be very useful. (On the other hand, users may themselves mark sections or paragraphs as obsolete, but this does not solve the problem of presenting the relevance of documentation to new users). I think that official documents often become outdated precisely because it does not display the date of its update.
In any case, I hope that I have written enough to convince you of the possibility of creating and benefiting from the standard documentation for open source projects. Both software users and its authors will benefit from this. Please leave your comment and let me know what you think about this.
Source: https://habr.com/ru/post/142197/
All Articles