Creating a system for blogging and working with documentation: Experience of the Kato messenger team

During the development of the messenger for Kato teamwork , we tried a large number of tools for creating and editing texts (documentation, blog, etc.). It would seem that you need to choose the appropriate engine for publishing materials, and the deal is with the end, but in practice everything turned out to be much more complicated and we had to create our own system.

Start of the journey: Quora

We began our journey into the world of working on content using the popular Quora Q & A service and started a blog on this platform. Subsequently, it turned out that this decision was somewhat premature, because at that time Quora did not allow search engines to index content.

In addition, the search inside the service worked extremely poorly (this problem is still present). All this made using Quora as a system for blogging and publishing product descriptions virtually impossible. We had to abandon this platform.

Ghost and HelpScout

The next stop was the use of the Ghost blogging platform (we planned to use it for its intended purpose) and the HelpScout system for maintaining documentation. At this stage, the minuses of the approach to the separation of blog posts and documentation became obvious - most often it happened that a blog post pulled a separate article for the help section in the product description.



In addition, the limitations of the selected tools appeared - Ghost had a convenient editor and worked very stably, but it was very annoying that there was no search (there wasn’t even a search for publication names). Note that we started using the Ghost system at an early stage of its development - today it is a great engine with which you can do almost anything.

HelpScout had a very moody editor, which was very difficult to work with - updating a post without breaking all the formatting was a non-trivial task.

Wordpress

The longest and most difficult period of searching for the ideal system for working with content was the use of Wordpress. We wrote our own theme for Wordpress. Then the difficulties began - the system constantly “fell” and worked extremely unstable. As a result, we had to configure blog accessibility monitoring, develop a thin caching system, and so on.

The complexity of the process was added by the need to look for various plugins - for example, for Markdown, which we actively use - and constantly update Wordpress itself (after each update, something that previously worked fell off). In addition, the ability to co-edit documents was not very convenient in this engine.

What should be in the system for working with content

In general, we were forced to reject Wordpress, but the plus of our suffering with this engine was that the requirements for the system for working with content were finally formed.

So, we needed:

• The ability to store documents on a static site (no PHP, Node.js, Rails);
• There is a URL structure that allows you to work with translations (the documentation must be translated into different languages);
• The most important thing is the ability to engage our readers in translating and improving documentation articles (bug fixes, suggestions for improvements, etc.).

Based on these requirements, we have created our own system, described below.

Git, Markdown and GitHub

The system uses the Git repository with documents in Markdown format, the manifest.json file in which describes a site with all translations, categories of documents and pages.

The following is an example of a description of the page structure of a documentation section:

{
                    "type": "category",
                    "title": "Notifications",
                    "src": "notifications",
                    "entities": [
                        {
                            "type": "page",
                            "src": "noise-control",
                            "title": "Noise Control"
                        },
                        {
                            "type": "page",
                            "src": "audio-notifications",
                            "title": "Audio Notifications"
                        },
                        {
                            "type": "page",
                            "src": "auto-hide-notifications",
                            "title": "Auto-hide Notifications"
                        },
                        {
                            "type": "page",
                            "src": "group-mentions",
                            "title": "Group Mentions"
                        }

A special script (written in haste) passes through this file and creates a static tree from it with the final html files. In the form of styles, we used the Wordpress theme created at the previous stage with minor changes.



At the bottom of each page there is a special button associated with GitHub, clicking on which the reader can correct this document in his fork and suggest a change in the form of a pull request. The pages themselves on GitHub are layout in Markdown markup.



Fork of Kato documentation on GitHub

The described scheme can not be called simple, but it is quite flexible and reliable. In addition, our product is mainly used by IT specialists, who cannot be confused, for example, by the presence of the “Vim style” command mode in the messenger .

That's all for today, we will be happy to answer questions in the comments!

PS If you liked our project and you know foreign languages ​​(except English and German - work is already underway with them), we will be very grateful for any help in translating the Kato documentation!