Have you ever come across a long search for documentation for your library or package? I find it odd that the source code does not come with user documentation. After all, it is just as important a part of the code as tests or dependencies. Without good user documentation, we can “kill” a lot of time analyzing code and comments. So why not store user documentation along with the source code of the program? This is not about DocBlock and the generation of project API documentation; I’m talking about user documentation, which we love so much for consistent narration and lots of examples.

In this article I will give one of the ways to store user documentation along with the source code of the program so that it is convenient for both developers and users.

Many article may seem "captain". If you feel salt spray on your cheeks and hear the sound of waves, immediately stop reading!

User Documentation

Unlike the documentation added directly to the source code (in the form of comments), user documentation is more “user-oriented,” so to speak. Imagine that you have been looking for a suitable library for a long time and suddenly a colleague called one that “may suit you”. You quickly find it on GitHub , but where to start? It is good if there is a README.md file in the root, but even reading it may leave a lot of questions. Usually, everything ends with one exhaustive example (if the library is not large) or a link to official documentation in the form of a Web site or a PDF document. After accessing one of these resources, you sigh with relief, carefully read several pages, study the top five examples, and begin to confidently use the library.
')

User documentation is the face of your project. The more accessible it is, the less users will abandon the idea of ​​studying your solution due to the problem of novelty.

Using a Web site or document as user documentation is a good solution, but it has several drawbacks:

• The documentation is separate from the project and it may be difficult for the user to access it.
• Responsibility for user documentation lies entirely on the shoulders of the developer. If the user finds errors or typos in it, it will be difficult for him (regarding the solution proposed in this article) to contact the developer and inform him about it.
• If the user decides to help the developer and translate the documentation into another language, it will also be problematic to do so.
• Documentation may become inaccessible due to technical reasons (a Web site has fallen, a link to a document has been lost, etc.) So now I will try to convince you of the usefulness of storing user documentation right inside the project.

As tests

Do you store the unit tests of your project with the code or in a separate repository? Usually they are in the tests directory and are an integral part of the project. With the documentation as well. It is a part of your project, but unlike tests, users do not need it to test the performance of your solution, but for quick and painless familiarization with it.

I suggest to allocate for user documentation a separate directory in your project. Let it be called docs and contains files with the md extension (why you will find Markdown selected later). It is also useful to provide your user documentation with an “entry point” - this is a table of contents file that will make it easier for users to navigate this directory. I prefer to call this file index.md and write to it a list of links to other files in this directory.


I also recommend using the “Introduction” file ( getting-started.md ), which can be used for “quick start”. It should be brief and accessible describes the main features of your solution with examples and comments. The information in this file should be enough to start using your solution at the user level.

The user documentation should have an “entry point” - a document that will familiarize the reader with the structure and content.

The remaining files should contain a detailed description of the components of your solution, detailed examples of use and possible problems that the user may encounter. It is better that these files are not related to each other, so that the user can begin to study the component that he considers necessary.

Directly to the repository

After the user documentation is ready, add the README.md file to the root of your project, which will contain a link to the “entry point” of your documentation.


Now the project can be committed and uploaded to your repository. If this is GitHub , then in addition to the source code, users will receive high-quality user documentation. As an example, I can offer my solution in the field of routing CLI requests, which used the approach proposed in the article.

Since all the documentation is in the repository, it is convenient to refer to it from the outside by the link of the form: https://raw.githubusercontent.com/Bashka/bricks_cli_routing/master/docs/call.md - and if you “tie” the Web interface here You can get a full-fledged website without the need to transfer documentation Convenient is not it?

Moreover, if you move the documentation from the docs directory to the docs / ru directory, then allow your users to translate it simply by adding new directories and copying the translated documentation files into them.

Bye all

If you are writing a small OpenSource solution, then try this method of storing documentation. It may seem obvious, but it is rarely used. Perhaps this is due to the fact that the project is written by some people, and the user documentation by others.