Each service provided by Selectel can be managed in your personal account - control panel . Many of our products can also be controlled via API requests. Product instructions and API documentation are available in a single help center .
The main idea of the help center is to provide our clients with the opportunity to independently find answers to most of their questions about Selectel services at any time convenient for them.
Next, we'll talk about how we changed the approach to preparing documentation and updated the appearance of the knowledge base.
The technical implementation of the knowledge base and its visual component three years ago fully covered all the needs of a reference book with information. But over the past time the company has not stood still, but has been actively developing, both by launching new services and developing existing ones.
About a year ago, we noticed that the existing online help did not meet the requirements of our customers:
- the navigation menu grew like a fruit tree that does not know the care of a gardener;
- search has ceased to be convenient;
- the visual design was gradually outdated.
Previously, the documentation for the API of our products was not publicly available - some were posted in the my.selectel.ru control panel , some were issued upon request, and some were completely described in a text format, which was kept up to date very problematic. Now knowledge of IT infrastructure automation and interaction with the backend of Selectel services on the API Documentation tab .
A small excursion into the past
Ten or fifteen years ago, few of the companies producing software in Russia could boast of having an online help. The operating manuals were written in Word format with the use of ever-moving styles, trying to apply the GOST standards created in the 70s of the 20th century to modern and constantly changing requirements.
The meme is still popular among technical writers:
To this day, there are companies that can already boast of a convenient site interface, but their documentation remains at the level of "download instructions in pdf format for 45 sheets."
In large companies, the knowledge base is strongly associated with technical support. In an ideal spherical world in a vacuum, the user should be able to independently find 80% of the answers to their questions, without contacting technical support.
A portal with documentation does not bring any clear profit, but it can save technical support time due to the script:
- The user ordered the service.
- Faced with unobvious moments when setting up.
- I wanted to contact technical support.
- I went to the knowledge base and found the information I needed myself.
- Didn't contact technical support.
- Profit!)
It is often believed that help information only helps users understand the services after they are connected. This was probably the case in the days when printed books with information on working in Windows were published. But now it is becoming just as important to openly show potential users how the service operates prior to purchase.
Most software companies develop APIs at some point for both internal use and customers. Companies share a set of inputs by releasing public APIs to enable customers to integrate their services with the company's products.
Many custom tasks can be automated, including using ready-made chunks of code as a constructor to create the most user-friendly infrastructure. But pieces of code without explanations of what it is, what it does and how to use it are of little use - you won't brute force to find out what methods are and what data they expect for input.
- What needs to be done to make the public API pleasant to use?As documentation for the API, they usually give a minimal example of interaction, which describes the methods (also called endpoints) and provides responses from the service. For example, using the Kubernetes API, you can automate working with clusters and nodes in Managed Kubernetes .
- Attach documentation!
What tasks were before us
Our visual solution stopped making it easy to find the articles we needed, and the existing menu turned into an unreadable "sheet". Unreadable documentation is just as bad as irrelevant texts. People are used to reading well-laid out materials. Blogs, social networks, media - all content is presented not only beautiful, but also easy to read, pleasing to the eye. Currently, the UX and UI requirements cannot be ignored, especially for such a huge array of texts.
With the development of technologies for the visual design of sites, we noticed that the appearance of our knowledge base is outdated. Merely using anchors and lists in KB articles didn't help. It was necessary to revise the entire structure of the documentation and the search engine.
Common problems with documentation
Generally absent or no one knows about its existence
Instruction that cannot be found is no better than an instruction that does not exist.
We solved this problem in the following way - we began to add links to useful articles in our monthly mailing list, add transitions on the product pages of the site, and also set up notifications for all interested company employees through a special channel in the corporate messenger.
Outdated and not updated in time
The documentation process is not built into the product development, the documentation is done on a leftover basis.
In our case, the product manager is also tasked with documenting this new functionality while working on new functionality.
The documentation is complex and poorly organized, it is easier to ask the technical support how to solve the problem.
Writing documentation for the sake of documentation is pointless, it should be easily accessible. The more options to find a document, the better.
We completely revised the design of the sections of our knowledge base, in some cases the universal templates did not work, so we had to actively interact with all stakeholders, be it a product manager, technical support or a front-end development team.
Moving API documentation to public space
One of the problems with using API documentation generated in OpenAPI, Swagger or some other generation tool is the complex integration with the rest of the site. It is necessary that users have easy access to all instructions and articles - it is inconvenient if endpoints are displayed in one view, and text descriptions of the same processes are displayed on another page.
Maintaining a single visual image
When creating a single help center, we needed to maintain a consistent display of instructions and specifications, using a bunch of "git + markdown + swagger".
How it works now
Technical implementation
The knowledge base was originally built around a combination of Confluence and a static page generator.
We ditched Confluence and moved on to Documentation-as-Code. Now all the source code for the knowledge base is typeset in Markdown format and is stored in the Git version storage system. A knowledge base site is built from the repository using the Hugo Static Site Generator.
The site is generated from the files contained in the master branch of the Git repository. Data can be updated only through a pull-request, which allows you to check all new sections of the documentation before they are published in the public domain. Such a system also facilitates the approach to making edits - company employees can always create a branch and add all the necessary changes to it.
More on Documentation as Code
The principle of "documentation as code" implies the use of the same tools for writing documentation as for creating code:
- text markup languages;
- version control systems;
- code review.
The main goal of this approach is to create conditions for the entire team to work together on the final result - a full-fledged knowledge base and instructions for using individual services of the product.
Working with swagger files
Selectel product developers create an API and upload comments to the code in swagger format - this is a text file in * .yaml format that can be used as a code. When the API is updated, the swagger file is also updated, which makes it easier to update the documentation.
The following technical solution is used for API documentation:
- git repository with swagger specification files in * .yaml format, grouped by product;
- git repository with translations of swagger specifications in * .json format;
- git repository with files in * .md format;
- files in the * .md format contain text descriptions and wrapped in special endpoint description tags that are pulled from the git repository with files in the * .json format;
- Hugo static site generator.
In addition to the structure of the repository, rules for working with it were developed:
- a style guide has been prepared - a checklist for swagger files, which developers check against when updating API specifications;
- the master branch of the git repository with files in the * .md format reflects the state of the current specifications and is de facto in production;
- Pull-Request to the master branch is carried out when updates are released into production.
Visual component
The first step was to revise the navigation and create rules according to which the sections of the knowledge base would be formed. Together with UX designers, we prepared an information architecture. The structure should be as transparent as possible so that the reader does not think: "Where can you find this article?" To summarize, there are two approaches:
- From the interface. The content duplicates the sections of the panel (separately for services). This was the case in the previous version of the knowledge base.
- From tasks. The titles of articles and sections reflect the tasks of the users.
In order to streamline the structure, we used a combination of these two approaches. Even in newer versions of the control panel with a well-thought-out UX and UI, it is necessary to explain at least the terms, since our products are technically complex and the users are very different.
In addition to updating the table of contents, we've improved the search and breadcrumbs. “Breadcrumbs” is the user's path to the current page with the ability to return to any level. In the previous version of the knowledge base, it was impossible to get into the table of contents and it was inconvenient, so in the new version we fixed it.
Each company makes API documentation according to its own vision of style, structure, and a sense of beauty. If we open 4-5 public APIs of different companies, then, of course, we will be able to catch some commonality: structure, voluminous code examples and syntax highlighting, long pages. Nevertheless, all examples will have special features. For example, localization of endpoint descriptions is rare, while the structure of endpoint descriptions most often looks the same.
Several recommendations for structuring API documentation:
Grouping endpoints
Besides providing information for each endpoint, if there are many endpoints, it is advisable to group them. The long continuous list of endpoints makes navigation difficult.
Separate description of methods
When using the GET / POST methods at the same time, only one method should be described in one line.
That is, the first line in this case is the description of GET, the second line is the description of POST, so you can avoid confusion.
Automation of making changes
Simplify making changes without manually reformatting each section - in our case, we only translate the text of the swagger file, without touching the markup thanks to the automation of this process, which our devops specialists have configured.
Syntax highlighting
Developers love code examples the most in the world, no developer will complain that there are too many examples - they greatly reduce the time to immerse in the product.
Working with pieces of code is much more convenient when different elements are colored appropriately depending on the programming language.
Since out-of-the-box code highlighting was available only for dark backgrounds, the frontend developer modified this solution using highlight.js to our corporate style.
Instead of a conclusion
The updated knowledge base has been available to users since March, and the API documentation has been available since the beginning of August.
“- With us, when you run for a long time, you certainly find yourself in another place.What we have already done is just another step towards improving the knowledge base. We will gradually add new instructions and documentation to the APIs of our other services.
“Well, here, you know, you have to run as fast to stay in the same place, and to get to another place, you need to run twice as fast.”
(Lewis Carroll "Alice Through the Looking Glass")