How not to turn the corporate knowledge base into chaos: our experience in dealing with Confluence

With a corporate knowledge base for developers, there is usually a problem - it either turns into a void, because there is no motivation to fill it or a responsible person, or - in a balcony filled with things from a Soviet apartment, everyone contributes, but they write chaotically, the information quickly becomes obsolete, and it does not always have time to update.

How to avoid this, or at least reduce the possible costs? How to make your corporate base warm and lamp? I'll try to answer.

Collab documentation

There is such an approach, collaborative documentation, it initially appeared in the field of medicine, when the decision to make a diagnosis is made collectively by the patient and several doctors.

A vivid example in the field of IT is Google Docs, Wiki, Github, any system where there are internal conventions and the possibility of collaborating on a project.

The idea is to include developers, experts, critics together in the work on documentation, to identify gaps together.

Why is it even needed?

First, to reduce the bus factor is the bottleneck in corporate knowledge, where the number of knowledge holders tends to be one. It is necessary to move such knowledge from the developer’s head, from whiteboards, tickets, kitchen conversations to a single space, so that everyone can work with them and contribute.

Secondly, to simplify the entry of newcomers into projects, which is especially important for distributed teams and teams with some outsourcing developers, as well as for those companies that have a very specific business area, and the chance to find a ready-made specialist is zero.

Thirdly, for the formation of a benign corporate culture, transparency “not in words”. The developer in such an environment clearly understands the points of professional growth, what other technologies he can try out in the company, what to learn.

What to do?

Documentation within the corporate knowledge base can be written by any team member, this opportunity should be simplified for them, then they will feel that they are owners of the result - involved.

However, you definitely need a person who will take over the functions of the information architect - he will set uniform rules, structure, logic, style, and correctly place the documents in the spaces.

Open the possibility of editing and creating documents to team members, having previously agreed on the rules of the game. Automate these rules to the maximum - do not rely on the team, create templates, tag content automatically, set up uploading from the repository to the knowledge base (I want to make a separate article about this, by the way).



It is important that developers see that documents do not go off to die in the corporate Wiki. An important principle: the definition of done internal document, this is the moment when it made changes or comments , that is, in fact, the moment of collaboration. This is its value, they want to spend time on it. Do not complement - it means that the delivery process, the implementation of the search is poorly adjusted, or the tool is inconvenient.



The potential problems of such an approach are the accumulation of edits and comments like a snowball, it is difficult to keep track of, and duplicate documents are often created.

To prevent this from happening, you can and should: A. Ask the team a vector, a set of rules and complicate the process of not following them (for example, we in Confluence hid the “Create” button and make the template selection mandatory). B. Cleverly differentiate rights and set up editing processes conveniently for the person responsible for the information architecture.

And then the perfect world will come

Developers will not stop asking each other questions, including stupid and repetitive . They will not learn to find all the answers in the knowledge base on their own. We have internal humor when, because of the limitations of the search index Confluence, developers cannot find something, they ask me as an information architect. We call it Sveta-based search.

Despite these limitations, the very structure of the knowledge base, uniform naming of pages, and the use of labels will encourage them to seek and create knowledge, for example, not to answer constantly repeated questions.

Another life hacking that we have applied is to always include the business context in the documents, even if it is a library or class description or checklist for a task, it is important to understand what this means for the client.

---

And now to practice

Next is the “How” part, which internal Confluence capabilities (yes, we use the Atlassian stack) can be used to implement these principles.

Templates

We have created ready-made templates for different types of documents that we most often write - technical specification, how-to, checklist. They can be configured in the admin space panel. Templates are needed so that when creating a document, the developer does not see a blank page in front of him, he already has instructions on what to write in this or that section. If you want documents of a certain type to fall into one section and meta information is displayed on them (this is convenient, for example, to describe the components of a complex product or a set of microservices using the same scheme), then create a blueprint, this is like a template at maximum speeds.



In them we set up page layout, headings, where only a few words will remain, a status header, images, tables, code blocks, and even variables.

Variables are preconfigured content items to which a subsequent document editor should assign a value, for example, enter text or select from a list.

You can also add to the template in advance if you add tags to a narrow document, you can mention users as reviewers, for example, if there is a clear name-based workflow for the statement, Jira macro, and attach a ticket from Jira. Our experience shows that you can cover up to 80 percent of your tasks with templates.

Page layout

Another important element is the creation of a clear and beautiful landing page in the command space. To do this, we use page layout (page layout) and macros Panel, Column and Section.

Below is an example of one of our development team spaces.



Use clear page names. As you probably know, Confluence does not support the same page names within the same space. Maintain clear page names, such as

Bad Python

name. Good Python Styleguide name for the internal services team.

Labels

Confluence has some limitations of the search algorithm related to content indexing. And for the corporate knowledge base, it is the findability and connectivity that are the most pressing issues. We have a whole article in our knowledge base, called How to beat the Confluence Search, if you want, I will share it in the comments.



To overcome these limitations, we use a system of labels. In fact, these are tags that mark the subject of content, and why they allow you to aggregate the content of a specific subject in one place in the form of a kind of RSS Feed (Content by Label macro). So we have customized indexes.

If you already have hundreds of pages in the database, then I advise you to start with the following exercises:

• See the list of all labels at the following URL https: // <my-host-name> /labels/listlabels-alphaview.action.
• Find all content not marked by any labels in the advanced search bar: type: page NOT labelText: [a TO z] NOT labelText: [0 TO 9].

What can you go and do right now?

• Give developers editing rights, but wisely.
• Think over the structure of the command space, make a convenient landing page.
• Customize the templates.
• Use labels.
• Go and edit someone else's document or write a comment, make this document work.