Using asciidoc to document a project

When our freelance team was faced with the task of documenting the project, the following requirements were formulated:

• As you know, programmers, as a rule, do not like writing documentation ... so the easier and more comfortable it is to write it, the more likely it is that they will write it.
  
  • Since we work from home, it should be possible to write documentation locally, on our own machine .
  • To do this comfortably, you need the ability to use your favorite text editor for this, no forms on the websites of a la wiki or systems tailored to a specific editor / IDE.
  • Everyone has different access to the Internet, and to rule out a situation when the documentation was not written solely because when the mood arose to write it according to the law of meanness, the Internet fell off — the Internet should not be required to write documentation.
• Documentation should be available to all who work on the project. This includes the ability to read it through the website as well as work with it as with ordinary local files .
• It is desirable that the documentation supports a thread markup language and hyperlinks , so that it is easy to read.
• The ability to edit the documentation from the browser (a la wiki) is desirable, but not very important (the developers will work with the files, so this feature can be useful mainly to the client, which is unlikely to directly edit the documentation).

As a result, having studied the existing solutions, I stayed on the AsciiDoc system. This is a utility that converts plain text files (using very simple and intuitive markup) to almost anything (html, docbook, man, etc.). The reasons for choosing AsciiDoc are as follows:

1. Very simple and intuitive markup language. In fact, looking at a text file with AsciiDoc markup, you do not even immediately guess that this is not just a plain text file, but a “file with markup” - it looks like a regular, neatly structured text file. In fact, before AsciiDoc was discovered, for many years I wrote ordinary text files in about the same style, without any thought to convert them into other formats later! The absence of explicit “markup” makes it very easy to read and edit text in a regular text editor.
2. In general, the “correct” format for technical documentation is DocBook . But write documentation in this format, with pens, with the help of special utilities ... brrr! And AsciiDoc can convert to DocBook format as well. Thus, it is possible to write the main part of the documentation in a simple and convenient AsciiDoc text format, and then convert it to DocBook and “comb” using specific DocBook features that are not in AsciiDoc - this should speed up and simplify the writing of documentation many times, even if It must be submitted in the DocBook format.
3. AsciiDoc can itself convert besides docbook to man and html formats, and if you need something else, you can convert it to any other format from docbook.
4. The appearance of the generated html is configured via css (however, while the default settings are fine with me).
5. AsciiDoc is quite small, smart, and at the same time incredibly extensible utility (however, I have not yet had the need to expand it).

Next, I quickly scrolled CGIshka, which, when I called, found inside the project a .txt file with the documentation corresponding to the requested url, converted it using asciidoc to html (with caching the html pages until the original .txt file was changed) and returned the resulting html.

As a result, the system now works as follows:

1. write regular .txt files in the documentation directory, locally, in your favorite text editor
2. between the developers these files are scrambled just like the source code of the project (patches or svn)
3. immediately after editing the text file, you can go to the corresponding url, and see it in html-format (html will be regenerated on the fly and cached until the next change in .txt)
4. we haven’t done it yet, but in fact, the asciidoc format is not fundamentally different from the markup used on the wiki, so providing an opportunity to edit documentation via the web a la wiki should not be a problem

References:

• On the AsciiDoc site, you can find a full description of its capabilities, plus see the source of the pages of the site itself in the .txt format (yes, the AsciiDoc site is written in asciidoc :)).
• I made up a cheat sheet . The plate is very relevant, because AsciiDoc has a lot of opportunities, but a very small number is really enough, and I want to have this short list at hand.
• Description of the installation and configuration of asciidoc, syntax highlighting for Vim, and my CGIs for generating html on the fly.