Hi all!
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 can no longer, I canβt, I canβt fill in hellish tons of unreadable tables and documents.
Surely each of you now imagined what Iβm talking about, and broke into a cold sweat: lists of surnames without alphabetical order, tables with hundreds of columns with a sloppy layout, tables with thousands of lines in which you need to erase your finger on the mouse wheel to look heading, tons of pages of unnumbered instructions, hundreds of letters sent to each other with data that need to be analyzed and systematized and stuffed into the same unreadable tables.
And so, when I cooled down a bit, 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 scatter over the network and the level of hell in the departments adjacent to the development will drop at least a little, and people (including me) will become a little happier.
Tools
Product documentation is often kept alongside code, which is a good thing. And non-product documentation is usually stored anywhere. Often people try to bring information from different places into Confluence, and we are no exception. So the rest of the story is 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, various charts. This is a very interesting and powerful tool, but if you don't know how to cook it, then you will get another dump of unreadable documents. I will teach you how to cook!
Macros
Almost all the magic of Confluence is built around macros. There are a lot of macros, and they can be combined with each other. They are paid and free, further there will be various examples of macros with links to documentation for them.
The interface for working with macros is as simple as possible. To add a macro, you need to click on the plus and select the desired element 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 a macro needs something inside it to work, it looks like a box.
At the same time, you can put as many others as you like inside one frame, as long as there is logic in your pyramid.
Each macro has a preview: it immediately shows whether you have filled in 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 rights to create or edit templates themselves can create pages. You can add additional instructions to the template about how the page should be maintained.
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 spoiled. And it can be successfully used and even improved. More on that below.
Filtering (paid plugin)
Any huge unreadable table can be made a little less huge and a little more readable using filtering. To do this, you can use a paid macro .
Inside this macro, you need to shove a table (even the ugliest one is possible, the main thing is to shove it entirely). In the macro, you can select columns for drop-down filter, text filter, numeric, and date filter.
Just imagine that all information on candidates for all vacancies is recorded in a tabular list. Naturally, unsorted - people do not come to interviews in alphabetical order. And you need to understand if you have interviewed a specific applicant before. You just need to put this hell in a filter macro, add a text filter by last name - and voila, the information is on your screen.
It is worth noting that filtering huge tables can affect system performance and page load 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).
Sorting (paid plugin)
With Magic Macro you can also set the default sorting on any column and number the rows. Or click on any column of the table put 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 held in a certain month - sort by date and rejoice.
Pivot Tables (paid plugin)
Now let's move on to a more interesting case. Imagine that your table is huge and you need to calculate something on it. Of course, you can copy it to Excel, calculate what you need and upload the data back to Confluence. Can you apply a macro once? and get the same result, only updated.
For example: you have a table that contains the data of all employees - where they are geographically located and what positions they hold. To calculate how many people are in each city, you need to select in the "Pivot Table" macro the row by which the data is aggregated (location) and the type of operation (addition).
Naturally, you can group according to several criteria at once, you can see all the possibilities .
Charts (paid plugin)
As I said, not everyone loves tables as much as I do. Unfortunately, most managers don't like them at all. But everyone loves bright color charts.
The creators of Confluence certainly knew about this (for sure they also have bosses who love reports and charts, where would they be without it). Therefore, you can use the magic macro . In this macro, you need to put the pivot table from the previous paragraph, and voila - your boring gray data is beautifully visualized.
Naturally, this macro also has settings. A link to the documentation for any macro can be found in the edit mode of that macro.
Ease of aggregation
The information from 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.
Tags
It's bad when people store information in one unstructured article or a huge table. Even worse is when parts of this information are not only unreadable, but also scattered across the expanses of Confluence. Fortunately, it is possible to collect scattered information in one place. For this you need to use (tags familiar to everyone on social networks).
Any number of tags can be added to any page. Clicking on a tag will take you to an aggregation page with links to all content with that tag, as well as a set of related tags. Related tags are those that appear frequently on the same page.
Page properties
You can add another interesting macro to the page for structuring information - . 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 the page will still be marked with the necessary keys.
Pay attention to the ID - it is convenient to set it to hang different groups of properties on different pages (or even different groups of properties on one page).
Reports
By tags, you can collect reports. For example, macro collects all pages with a certain set of tags.
But a more interesting report is a macro . It also collects all pages with a certain set of tags, but does not just list them, but compiles a table (do you catch the connection with the beginning of the article?), In which the columns are the keys of the page properties.
It turns out a summary table of information from different sources. It's nice that it has convenient features: adaptive layout, sorting by any column. Also, such a reporting table can be configured inside the macro.
When configuring, you can remove some columns from the report, set the default state or the number of displayed records. You can also set the page property ID to see only the information you need.
For example, you have a lot of employee pages, 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 id = employee_inf. And there is a second set of properties on the same page, which contains information about a person as part of a team: what role the person performs, what team he is in, and so on. These properties are marked ID = team_inf. Then, when compiling a report, you can display only information for one ID or two at once - whichever is more convenient.
The beauty of this approach is that everyone can collect the information table they need, which will not duplicate anything and will be updated when the main page is updated. For example: a team leader does not care when his developers got a job, but it is important what role each of them plays in the team. The team leader will collect a report on the team. And the accountant doesnβt care who performs what role, but the positions are important - he will collect a report on the positions. In this case, the source of information will not be duplicated or transferred.
Final process
Instructions
So, we can beautifully structure and effectively aggregate information in Confluence using macros as an example. But ideally, you need to make sure that new information is immediately structured and gets into all the aggregation mechanisms already in use.
Here a bunch of macros and templates will come to the rescue. To get people to create new pages in the right format, you can use the Create from Template macro. It adds a button to the page, by clicking on which a new page is created from the template you need. This way you make people immediately work in the format you need.
In the template from which you allow to create 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 ββto fill the page with and property values.
Then the final process will look like this:
- You are creating a template for a specific type of information.
- In this template, add labels and page properties in a macro.
- In any convenient place, create a root page with a button, by clicking on which a child page is created from the template.
- Start up on the root page of users who will potentially generate the necessary information (according to the desired template, by clicking on the button).
- Collect yourself a report on the properties of the page through the tags that you specified in the template.
- Rejoice: you have all the information you need in a convenient format.
Pitfalls
As a quality engineer, I can safely say that there is nothing perfect in the world. Even divine tables are imperfect. And there are pitfalls in the above process.
- If you decide to change the names or composition of the page properties, you will have to update all the already created objects so that their data is correctly pulled into the summary report. This is sad, but on the other hand, it forces you to think in detail about the "architecture" of your information set, which is a very interesting task.
- You will have to write a decent amount of instructions on how to fill in the information tables and use the tags. But, on the other hand, you can just throw this article at all the right people.
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: once users get used to it, they stop making 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 keeps all his 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: the card tag employee-card, direction tag direction-involve and command tag team-qa.
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 different points. Resource managers can collect general tables for themselves, and team leads can collect command tables by adding a team tag to the selection.
By tags, you can see different summaries, for example, by qa-upgrade-plan all tasks for QA development will be displayed. At the same time, each person in his employee card keeps an important story and his own development plan - he creates a nested page from the development plans template.
Conclusion
Keep any documentation in such a way that you are not ashamed of it, and users are not excruciatingly hurt!
I really hope that the article will be useful and order will come in all the documentation of the world.
Source: habr.com