🙏🏾 👩🏾‍🤝‍👨🏻 👂🏻 Design at Confluence 💵 👨🏼‍💼 😫

Hello everyone!

My name is Masha, I work as a quality assurance engineer in the Tinkoff group of companies. QA work involves a lot of communication with different people from different teams, and I was also a manager and lecturer of educational programs, so my communication map was as wide as possible. And at some point I exploded: I realized that I could no longer, could not, could not fill the hell of tons of unreadable tables and documents.

Surely each of you now imagined what I was talking about and swept in cold sweat: lists of surnames without alphabetical order, tables of hundreds of columns with a layout that had moved out, tables of thousands of lines in which you need to erase your finger on the mouse wheel to watch heading, tons of pages of non-numbered instructions, hundreds of data letters sent to each other, which must be analyzed and systematized and stuffed into the same unreadable tables.

And so, when I got a little cold, I decided to write this article. I will talk about how you can normally (even sometimes conveniently) maintain a variety of non-product documentation. I hope that the article will spread across the network and the level of adishment in the departments adjacent to the development will decrease even slightly, and people (including myself) will become a little happier.

Tools

Product documentation is often kept close to the code, which is good. And non-product documentation is usually stored anywhere. Often people try to transfer information from different places to Confluence, and we are no exception. So the whole further story about him.

In general, Confluence is an advanced wiki engine. It allows you to work with data in different types of display: text with formatting, tables, a variety of diagrams. This is a very interesting and powerful tool, but if you do not know how to cook it, then you will get another dump of unreadable documents. I will teach you how to cook!

Macros

Almost all Confluence magic is built on macros. There are a lot of macros, and they can be combined with each other. They are paid and free, then there will be different examples of macros with links to the documentation for them.

The macro interface is as simple as possible. To add a macro, click on the plus and select the desired item from the list.

If the macro is self-sufficient, that is, it does not require the insertion of something else inside itself, it looks like a block.

If for the macro to work, you need to put something inside it, it looks like a frame.

At the same time, you can put as many others as you like inside the frame, if only there is logic in your pyramid.

Each macro has a preview: it immediately shows whether you have completed and configured the macro correctly.

Patterns

In addition to macros, there is a convenient tool for pre-filling content - this is a template.
Templates can be used when creating any page: just click on the three dots next to the "Create" button and select the desired template.

Then all the content that is in the template will be added to the created page.

Anyone can create pages from templates, but only those who have the right to create or edit templates themselves. You can add additional instructions to the template on how to maintain the page.

Table magic

Actually, as a techie, I dearly love tables and can wrap almost any information in them (although this is not always effective). The tables themselves are clear, structured, scalable, magical!

But even such a wonderful entity as a table can be ruined. And you can successfully use and even improve. About it below.

Filtering (paid plugin)

Any huge unreadable table can be made a little less huge and a little more readable by filtering. To do this, you can use the paid macro "Filter tables . "

Inside this macro you need to stick the table (you can even the ugliest, the main thing is to push it in whole). In the macro, you can select the columns for the filter with a drop-down list, a text filter, a numerical filter and a filter by dates.

Just imagine that all the information on the candidates for all vacancies is recorded in a tabular list. Naturally, unsorted - people do not come for interviews alphabetically. And you need to understand if you have interviewed a particular job applicant before. You just need to put this hell into the filter macro, add a text filter by last name - and voila, the information on your screen.

It is worth noting that filtering huge tables can affect the system and page loading time, so putting a huge table in the filter is a temporary crutch, it is better to build a process in which people do not have to create huge unreadable tables (an example of the process will be at the end of the article).

Sort (paid plugin)

Using the magic macro “Table Filter” you can also set the default sorting by any column and number the rows. Or click on any column of the table that is popped into the filter macro, and sorting by this column will occur.

For example, you have the same table with applicants and you need to figure out how many interviews were conducted in a particular month - sort by date and be happy.

Summary tables (paid plugin)

Now let's move on to the case more interesting. Imagine that your table is huge and you need to calculate something from it. Of course, you can copy it to Excel, calculate what you need and upload the data back to Confluence. Or you can apply the “Pivot Table” macro once and get the same result, but also updated.

For example: you have a table in which data of all employees is collected - where they are located geographically and what positions they occupy. To calculate how many people are in each city, you need to select in the macro “Summary table” a row by which data (location) and type of operation (aggregation) are aggregated.

Naturally, you can group by several criteria at once, all the features can be found in the documentation .

Charts (paid plugin)

As I said, not everyone likes tables as much as I do. Unfortunately, most of them do not like managers at all. But everyone loves vibrant color charts.
The creators of Confluence, of course, knew about this (they probably also have a boss who loves reports and charts, but where without it). Therefore, you can use the magic macro "Chart from the table . " In this macro you need to put the pivot table from the previous paragraph, and voila - your gray boring data is beautifully visualized.

Naturally, this macro also has settings. A link to the documentation for any macro can be found in the editing mode of this macro.

Ease of aggregation

The information in the previous paragraphs was probably not a revelation for you. But now you definitely know how to use macros, and I can move on to the more interesting part of the article.

Page Properties

You can add another interesting macro to the page for structuring information - “Page Properties” . Inside it, you need to submit a table of two columns, the first will be the key, and the second will be the value of the property. Moreover, the macro can be hidden from the page so that it does not interfere with reading the content, but at the same time the page will still be marked with the necessary keys.

Pay attention to the ID - it is convenient to set it to hang different property groups on different pages (or even different property groups on one page).

Reports

By tags, you can collect reports. For example, the Content Report macro collects all pages with a specific set of tags.

But a more interesting report is the "Page Properties Report" macro . It also collects all pages with a specific set of labels, but does not just display a list of them, but compiles a table (catch the link to the beginning of the article?), In which the columns are the keys to the page properties.

It turns out a summary table of information from various sources. It's nice that it has convenient functions: adaptive layout, sorting by any column. Also, such a reporting table can be configured inside a macro.

When configuring, you can remove some columns from the report, set the default state or the number of records displayed. You can also set the page property ID to see only the information you need.

For example, you have many pages of employees, these pages have a set of properties about a person: what level he is, where he is, when he joined the team, and so on. These properties are marked with ID = employee_inf . And there is a second set of properties on the same page that collects information about the person, as part of the team: what role the person performs, in which team he is, and so on. These properties are marked with ID = team_inf . Then, when assembling the report, you can display only information about one ID or just two at once - as it is more convenient.

The beauty of this approach is that everyone can collect the information table that they need, which will not duplicate anything and will be updated when the main page is updated. For example: Timlidu is not important when his developers got a job, but it is important what role each of them plays in the team. Timlid will collect a report on the team. And the accountant doesn’t care who performs what role, but the posts are important - he will collect a report on the posts. In this case, the source of information will not be duplicated or transferred.

Final process

Instruction manual

So, we can beautifully structure and efficiently aggregate information in Confluence using macros as an example. But ideally, it is necessary to make sure that the new information is immediately structured and falls into all already used aggregation mechanisms.

Here a bunch of macros and templates will come to the rescue. To make people create new pages in the right format, you can use the "Create from Template" macro. He adds a button to the page, by clicking on which a new page is created from the template you need. Thus, you make people immediately work in the format you need.

In the template from which you are creating a page, you need to add labels, the “Page Properties” macro and a table of the properties you need in advance. I also recommend adding instructions on what values should fill the page, and property values.

Then the final process will look like this:

You create a template for information of a certain type.
Add tags and page properties in the macro to this template.
In any convenient place, create a root page with a button, by clicking on which a child page from the template is created.
Launch on the root page of users who will potentially generate the necessary information (according to the desired template, by clicking on the button).
Gather a report on the properties of the page through the labels that you specified in the template.
Rejoice: you have all the necessary information in a convenient format.

Underwater rocks

As a quality engineer, I can safely say that there is nothing ideal in the world. Even divine tables are imperfect. And in the above process, there are pitfalls.

If you decide to change the name or composition of the page properties, you will have to update all already created objects so that their data is correctly pulled into the summary report. This is sad, but, on the other hand, it makes you think through the “architecture” of your set of information in detail, which is a very interesting task.
You will have to write a decent amount of instructions on how to fill out information tables and use tags. But, on the other hand, you can just throw all the right people in this article.

An example of storing non-product documentation

Through the process described above, you can organize the storage of almost any information. The beauty of the approach is that it is universal: when users get used to it, they stop generating a mess. Also a big (but not free) plus is the ability to collect various statistics on the fly and draw beautiful diagrams on it.

I will give an example of our process of maintaining information about the team.

For each person in the team, we decided to create an employee card. Accordingly, we have a template according to which each new person creates this card for himself and maintains all personal information in it.

As you can see, we have a detailed table of properties and immediately have instructions on how to maintain this page. Some of the tags are put down by the employees themselves according to the instructions, in the template only the main ones: card tagemployee-card , direction tag -direction and team-qa tag .

As a result, after everyone has created a card for themselves, a complete table with information on employees is obtained. This information can be used at various points. Resource managers can collect general tables for themselves, and team leads can create team tables by adding a team tag to the selection.

You can see different summaries by tags, for example, by qa-upgrade-plan all tasks for QA development will be displayed. At the same time, each person in his employee card leads an important story and his development plan - creates an embedded page from the template for development plans.

Conclusion

Keep any documentation so that it is not embarrassing, and users are not excruciatingly hurt!

I really hope that the article will be useful and that all documentation of the world will be in order.

Design at Confluence