{"id":76463,"date":"2020-04-02T13:42:40","date_gmt":"2020-04-02T11:42:40","guid":{"rendered":"https:\/\/prohoster.info\/blog\/administrirovanie\/proektirovanie-v-confluence"},"modified":"2020-04-02T13:42:40","modified_gmt":"2020-04-02T11:42:40","slug":"proektirovanie-v-confluence","status":"publish","type":"post","link":"https:\/\/prohoster.info\/en\/blog\/administrirovanie\/proektirovanie-v-confluence","title":{"rendered":"Designing in Confluence","gt_translate_keys":[{"key":"rendered","format":"text"}]},"content":{"rendered":"

Hello everyone! <\/p>\n

My name is Masha, and I work as a quality assurance engineer at Tinkoff Group. The QA role requires extensive communication with various people from different teams, and I have also been a manager and lecturer for educational programs, which broadened my communication map significantly. At one point, I hit a breaking point: I realized I could no longer fill out endless amounts of unreadable tables and documents. <\/p>\n

\"Designing
\n
\n<\/a><\/noindex>
\nI'm sure each of you can now picture what I'm talking about, and you might even be sweating: lists of names without alphabetical order, tables with hundreds of columns and misaligned formatting, thousands of rows that require you to scroll with your finger on the mouse wheel just to see the header, tons of pages of unnumbered instructions, and hundreds of emails being shuffled around with data to analyze, systematize, and stuff back into unreadable tables.<\/p>\n

\"Designing
\n
\nSo, when I calmed down a bit, I decided to write this article. I will talk about how to properly (and sometimes even conveniently) manage various non-product documentation. I hope this article gets shared widely online, reducing the level of chaos in departments adjacent to development just a bit, and that people (including myself) become a little happier.<\/p>\n

\"Designing
\n<\/p>\n

Tools<\/h2>\n

\nProduct documentation is often stored alongside the code, which is good. Non-product documentation, however, is usually scattered all over. People often try to transfer information from different locations into Confluence, and we are no exception. So here's my story about it.<\/p>\n

Overall, Confluence is an advanced wiki engine. It allows you to work with data in various display formats: formatted text, tables, diverse diagrams. It's a very interesting and powerful tool, but if you don't know how to prepare it properly, you'll end up with yet another heap of unreadable documents. I'll teach you how to get it ready!<\/p>\n

\"Designing
\n<\/p>\n

Macros<\/h2>\n

\nMost of Confluence's magic is built on macros. There are a lot of macros, and they can be combined with each other. Some are paid, and some are free; I'll provide various examples of macros along with links to their documentation.<\/p>\n

The interface for working with macros is as simple as possible. To add a macro, you just need to click on the plus sign and select the desired item from the list.<\/p>\n

\"Designing
\n
\nIf the macro is self-sufficient, meaning it does not require anything else to be inserted inside it, it looks like a block.<\/p>\n

\"Designing
\n
\nIf the macro requires something to be placed inside, it resembles a frame.<\/p>\n

\"Designing
\n
\nYou can place as many other elements inside a single frame as you want, as long as there is logic to your pyramid.<\/p>\n

\"Designing
\n
\nEach macro has a preview: it immediately shows whether you have filled out and configured the macro correctly.<\/p>\n

Templates<\/h2>\n

\nIn addition to macros, there is a convenient content pre-filling tool \u2014 it's a template.
\nTemplates can be used when creating any page: just click on the three dots next to the 'Create' button and select the desired template.<\/p>\n

\"Designing
\n
\nThen all the content from the template will be added to the created page.<\/p>\n

Anyone can create pages from templates, but only those with permissions can create or edit the templates themselves. Additional instructions on how to manage the page can be added to the template.<\/p>\n

\"Designing
\n<\/p>\n

The Magic of Tables<\/h2>\n

\nAs a techie, I naturally love tables and can wrap almost any information in them (even if it's not always effective). Tables, in and of themselves, are clear, structured, scalable, and magical!<\/p>\n

\"Designing
\n
\nBut even such a wonderful entity as a table can be ruined. However, it can also be used successfully and even improved. More on that below.<\/p>\n

Filtering (paid plugin)<\/h3>\n

\nAny large unreadable table can be made somewhat less enormous and a bit more readable through filtering. For this, a paid macro can be used. \"Table Filter\"<\/a><\/noindex>.<\/p>\n

You need to insert the entire table into this macro (even the ugliest one, as long as you fit it all in). You can select columns for filtering with a dropdown list, a text filter, numeric filters, and date filters within the macro. <\/p>\n

\"Designing
\n
\nImagine that all the information about candidates for all positions is recorded in a tabular list. Naturally, it is unsorted \u2014 people don\u2019t come for interviews in alphabetical order. And you need to determine whether you have interviewed a specific candidate before. You just need to stuff this chaos into the filter macro, add a text filter by last name \u2014 and voila, the information is at your screen.<\/p>\n

\"Designing
\n
\nIt is worth noting that filtering large tables can affect system performance and page loading times, so putting a huge table into a filter is a temporary workaround. It's better to establish a process where people aren't forced to create huge, unreadable tables (an example of this process will be at the end of the article).<\/p>\n

Sorting (paid plugin)<\/h3>\n

\nWith the magical macro \"Table Filter\"<\/a><\/noindex> , you can also set a default sort by any column and number the rows. Or just click on any column of the table embedded in the filter macro, and it will sort by that column. <\/p>\n

\"Designing
\n
\nFor example, if you have the same table with candidates and need to estimate how many interviews were conducted in a specific month, sort by date and enjoy.<\/p>\n

Pivot tables (paid plugin)<\/h3>\n

\nNow let\u2019s move on to a more interesting case. Imagine that your table is huge and you need to compute something from it. Of course, you could copy it to Excel, calculate what you need, and upload the data back to Confluence. But you could just apply the macro \u201cPivot Table\u201d<\/a><\/noindex> once and get the same result, but also keep it updated.<\/p>\n

For example, you have a table that collects data on all employees\u2014where they are located and what positions they hold. To count how many people are in each city, you need to select in the \u201cPivot Table\u201d macro the row by which the data is aggregated (location) and the operation type (summation).<\/p>\n

\"Designing
\n
\nNaturally, you can group by several criteria at once; all the options can be viewed documentation<\/a><\/noindex>.<\/p>\n

Charts (paid plugin)<\/h3>\n

\nAs I mentioned, not everyone loves tables as much as I do. Unfortunately, most managers don\u2019t like them at all. However, everyone loves bright, colorful charts.
\nThe creators of Confluence undoubtedly knew this (they most likely have bosses who love reports and charts, after all). So, you can use the magical macro \u201cChart from Table\u201d<\/a><\/noindex>. You need to insert the pivot table from the previous section into this macro, and voila\u2014your gray, boring data is beautifully visualized.<\/p>\n

\"Designing
\n
\nOf course, there are also settings in this macro. You can find the documentation link for any macro in the editing mode of that macro.<\/p>\n

Ease of aggregation<\/h2>\n

\nThe information from previous points was surely not a revelation for you. But now you definitely know how to use macros, and I can move on to a more interesting part of the article.<\/p>\n

\"Designing
\n<\/p>\n

Tags<\/h3>\n

\nIt\u2019s problematic when people store information in a single unstructured article or a huge table. Even worse is when parts of this information are not only poorly formatted but also scattered across the vastness of Confluence. Fortunately, there is a way to gather all that scattered information in one place. For this, you need to use tags<\/a><\/noindex> (familiar to everyone from social networks).<\/p>\n

\"Designing
\n
\nYou can add any number of tags to any page. If you click on a tag, you will be taken to an aggregation page, which contains links to all materials with that tag, as well as a set of related tags. Related tags are those that frequently appear on the same page.<\/p>\n

\"Designing
\n<\/p>\n

Page Properties<\/h3>\n

\nYou can add another interesting macro for structuring information to the page \u2014 \u201cPage Properties\u201d<\/a><\/noindex>. You need to feed it 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 doesn\u2019t interfere with reading the content, but the page will still be marked with the necessary keys.<\/p>\n

\"Designing
\n
\nNote the ID \u2014 it is convenient to assign it so that different groups of properties can be attached to different pages (or even different property groups on the same page). <\/p>\n

Reports<\/h3>\n

\nYou can generate reports based on tags. For example, the macro \u201cContent Report\u201d<\/a><\/noindex> collects all pages with a specific set of tags.<\/p>\n

\"Designing
\n
\nBut a more interesting report is the macro \u201cPage Properties Report\u201d<\/a><\/noindex>. It also gathers all pages with a specific set of tags, but instead of simply listing them, it creates a table (catching the connection with the beginning of the article?), where the columns are the keys of the page properties.<\/p>\n

\"Designing
\n
\nIt results in a summary table of information from various sources. It\u2019s nice that it has convenient features: responsive layout, sorting by any column. This report table can also be configured within the macro. <\/p>\n

\"Designing
\n
\nWhen configuring, you can remove certain columns from the report, set a default state, or specify the number of displayed records. You can also set the page property ID to see only the desired information.<\/p>\n

For example, you have multiple employee pages, and each of these pages has a set of properties about the person: their level, where they are located, when they joined the team, and so on. These properties are marked. ID = employee_inf<\/i>. And there is a second set of properties on the same page, which contains information about the person as part of the team: what role the person performs, which team they belong to, and so on. These properties are marked. ID = team_inf<\/i>. Thus, when generating a report, you can display information by a single ID or at once for both\u2014whichever is more convenient.<\/p>\n

The beauty of this approach is that everyone can compile the information table they need, which will not duplicate anything and will be updated when the main page is updated. For instance: a team lead is not concerned with when their developers joined the company, but is interested in what role each of them plays in the team. The team lead will compile a report on the team. An accountant, on the other hand, does not care what roles are performed, but cares about the positions\u2014so they will compile a report on the positions. Meanwhile, the source of information will not be duplicated or moved.<\/p>\n

Final process<\/h2>\n

<\/p>\n

Instruction<\/h3>\n

\nSo, we can beautifully structure and effectively aggregate information in Confluence using macros as an example. But ideally, we need to ensure that new information is immediately structured and fitting into all the already-used aggregation mechanisms.<\/p>\n

Here, a combination of macros and templates will come to the rescue. To make people create new pages in the desired format, you can use the 'Create from template' macro. It adds a button to the page, which, when clicked, creates a new page from the template you need. This way, you ensure that people immediately work in the format you require. <\/p>\n

\"Designing
\n
\nIn the template from which you allow page creation, you should pre-add tags, the 'Page Properties' macro, and the table of required properties. I also recommend adding instructions on what values should fill the page, along with property values.<\/p>\n

\"Designing
\n
\nThen the final process will look like this:<\/p>\n

    \n
  1. You create a template for a specific type of information.<\/li>\n
  2. In this template, you add tags and page properties in the macro.<\/li>\n
  3. Create a root page in any convenient location with a button that generates a child page from the template when clicked. <\/li>\n
  4. Allow users on the root page who can potentially generate the needed information (using the specified template by clicking the button).<\/li>\n
  5. Gather a report on the page properties through the tags you specified in the template.<\/li>\n
  6. Rejoice: you have all the necessary information in a convenient format. <\/li>\n<\/ol>\n

    \"Designing
    \n<\/p>\n

    Pitfalls<\/h3>\n

    \nAs a quality engineer, I can confidently state that nothing in the world is perfect. Not even divine tables are flawless. And there are pitfalls in the above process.<\/p>\n