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

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

Start of the road: Quora

We began our journey into the world of working on content using Quora, a popular Q & A service, and started a blog on this platform. Subsequently, it turned out that this decision was somewhat premature, since 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 posting product descriptions virtually impossible. We had to abandon this platform.

Ghost and HelpScout

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



In addition, the limitations of the selected tools also appeared - Ghost had a convenient editor and worked very steadily, but the lack of search strained a lot (there was not even a search for publication names). Note that we started using the Ghost system at an early stage of its development — today it is an excellent engine with which you can do almost anything.

HelpScout was a very capricious editor, which was very difficult to work with - updating the post without breaking all the formatting was not a 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 Wordpress theme. Then the difficulties started - the system constantly “fell” and worked extremely unstable. As a result, we had to set up monitoring of the availability of a blog, develop a thin caching system, and so on.

The complexity of the process was added by the need to search for various plugins - for example, for Markdown, which we actively use - and to constantly update Wordpress itself (after each update, something that previously worked would fall off). In addition, the possibility of co-editing documents was not very conveniently implemented in this engine.

What should be in the system for working with content

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

So, we needed:

• The ability to store documents on a static site (no PHP, Node.js, Rails);
• Have a URL structure that allows you to work with translations (documentation must be translated into different languages);
• The most important thing is the opportunity to involve our readers in the work on translations and improvement of documentation articles (correction of errors, suggestions for improvements, etc.).

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

Git, Markdown and GitHub

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

Below is an example of the description of the page structure of the 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) traverses this file and creates from it a static tree with final html files. In the form of styles, the Wordpress theme created at the previous stage was used with minor changes.



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



Kato's Fork 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 are not confused, for example, by the presence of the command mode “in the Vim style” in the messenger.

Today, we will be happy to answer questions in the comments!

PS If you like 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 Kato documentation!