How to get the most out of Confluence. Chapter one
Hi, I’m Uliana, a senior analyst in product and system analysis in the Tinkoff Mobile Core department. Our department is responsible for developing common technical solutions — libraries used in mobile applications of the Tinkoff ecosystem.
For our colleagues we create documentation and manuals for the developed libraries, various joint projects and researches. Here are the main requirements for documentation: it should be as clear and structured as possible, and easy and quick to find.
We do our documentation in Confluence — and usually when I talk about Confluence, many people have unpleasant associations with it, to put it mildly. A million sections, awkward navigation, endless text, and many other things that discourage people from even opening a wiki. But I hasten to reassure you — things can be very different!
Let me tell you how to get the most out of Confluence, so you can learn how to use macros and other Confluence features to quickly create clear and easy to use documentation.
What is Confluence
Confluence is a tool for creating team spaces where all accumulated knowledge is stored. This knowledge is combined with collaboration capabilities.
Confluence is used for:
- Maintaining and storing project documentation and work materials.
- Structuring all information in a single place.
- Collaborative teamwork in real time.
- Optimization of team and project processes.
The main tools for working in Confluence are macros, markup, tags, and templates. Macros are one of the main tools in Confluence. Macros are the BASE of the basics!
Macros allow you to do tables, notifications, text layout, tabs, and many, many more.
It’s important to know and remember:
- Not all macros are available out of the box and are free. Be prepared that some of the listed macros may not be available or, on the contrary, are not described in this list because they are not available to me. Do not use all macros at once: they increase page loading time and may lead to utilization of the service resources as a whole — even up to full inaccessibility
- Don’t use all macros at once: they increase page load time and can lead to utilization of the service resources in general — even to the point of complete inaccessibility.
The main tools for editing wiki pages are brought to the top panel, and macros are hidden under the plus bar:
Macros open up the possibility to present information in a clear way and are divided into types:
formatting, layouts and images, internal content macros, external content macros, navigation, reports and using CSS.
How to set up the macros formatting
Formatting will help you visually highlight text and show its importance, hide bulky elements, and insert code into your documentation with syntax highlighting.
Information, Tip, Note and Warning — those macros are macro frames, you just need to put the information inside. When saving or in preview mode, the text will be highlighted.
Code block is a type of formatting macro where you can frame the code and set the desired parameters: syntax highlighting, block hiding, code line numbering and theme.
Expand helps to hide bulky information on the page, for example, if you need to add a large chart or table, additional information, or some backstory.
Panel displays text within a customizable panel. You can select the style and color of the frame, background color, text and title using HEX code.
With the Highlight you can highlight a specific part of the text, paragraph, as in a diary with a marker. You can choose the highlighting color yourself.
Round Rectangle macro is a graphical rounded rectangle that you can customize: set the header, set the footer, color and dimensions.
Alert helps you set up a pop-up notification on your Confluence page. For example, if the documentation is still in progress, so that when users log in to the page, they immediately see the alert information.
Alert can be configured in several views depending on the context: Success, Info, Warning, Error. Examples of display when saving:
Button Hyperlink and Button Group are macros that help you create hyperlinked buttons and organize them into related groups. You can create a button for both internal and external content, as well as customize the name, type and icon of the button, which will be linked when you tap on the button.
Section and Column are macros for text layout using columns combined into a section. Columns can be of any number and size. The main thing is to remember that columns need to fit on the page, otherwise it will be like rush hour in metro.
Horizontal Navigation Bar, Horizontal Page, Tabs Container Tabs and Page are macros for creating horizontal and vertical tabs. Be careful with this macro when designing important information: you may not find it when searching the page if you are not on a specific open tab.
How to customize schematic and image macros
Diagrams and images help you build charts and graphs, insert images, or build a roadmap.
PlantUML — for UML diagrams in documentation written in PlantUML. In the macro you need to insert the diagram with a picture, and if someone from the team wants to correct it, you just need to make edits to the code.
Gliffy diagram is the built-in editor for process modeling, also handy for teamwork. Although, I’ll be honest, my heart goes out to UML.
Spacegraph is a macro block that helps you perform complex operations in Confluence. It displays the structure of a space or partition as a diagram. You can configure in a specific space, specify limits on the number of blocks, change the design color and size.
We often use this macro on the introduction page to help the user navigate through the documentation.
Chart — In Confluence, you can build various graphs using data from a page for a specific need. Customize the chart type, screen orientation, size, title, subheading, axis name, colors, range of minimum and maximum values, and many more different parameters to make the chart unique to you.
Roadmap Planner — the name speaks for itself. You can build a Roadmap for a project using a macro. In my opinion, this macro is too simple for large projects, so I would recommend using other tools for Roadmap.
How to customize internal content macros
Internal content macros help you customize data organization, build analytics on internal data from wiki spaces, create polls and surveys, and reuse content in different parts of the documentation.
Table Filter helps to organize tabular data: hinge filters and sorting. You need to insert the table into the frame and set the necessary settings.
Table Excerpt, Table Excerpt Include and Chart from Table are macros that allow you to use a copy of a table to build summary tables and charts based on the same tabular data. Edits are made in one place, and they are automatically loaded everywhere.
How to customize table selection and insertion:
- Add Table selection.
- Set a unique name for the sample and frame the table with the data.
- Use the table selection insert macro to insert a copy of that selection.
- Specify in the insert macro the unique name inventoried for the table selection so that data from it is displayed in the insert.
The Chart from Table macro is used to create dynamic charts from table data, which we can specify explicitly with a table in a frame or pull up with an insert macro. Example of reusing data from a created table selection:
Forms — Confluence allows you to make various forms with surveys and polls. All data from the forms can be sent to email.
You need to insert a Forms macro, and into it everything that comes with the Forms prefix
Multiexcerpt and Multiexcerpt include free-entry macros.
How to customize:
- Add the multiexcerpt macro.
- Set a unique name and insert the data.
- Insert a copy of this sample using the multiexcerpt include macro (if necessary).
- Specify in the insert macro a unique name invented for the selection so that the data from it is displayed.
Task report — macro helps to create a report from specific sources, people, statuses. We in the team often use it for retro, 3Amigo and MN, so that we don’t lose fixed todos.
Content Report Table generates a table format content report based on the labels placed on the space pages. We use this macro to organize RFC and RND progress.
How to customize external content macros
External content macros help you set up communication with Jira, display data from Figma, Miro and other sources, and build various reports and analytics on related external content.
Jira embeds a task or filter from Jira.
Structure.Gantt is a macro to display a Gantt chart in Confluence if you are using Jira Structure. You only need to specify the ID of your structure. You can output a specific part from Structure, customize the automatic update period or the layout of the diagram.
Solution time — the macro displays a bar graph of the time taken to solve queries on a project or filter from Jira.
Sprint Status Gadget will help you visualize the status and progress of your sprint.
Voted Issues will show all tasks in work depending on the specified settings. The data is displayed for specific currentUser.
Widget Connector displays external content, you only need to specify the link.
How to customize navigation macros
Navigation macros help to structure information, organize cross-navigation between pages and make information search fast and convenient.
Livesearch helps you embed a search field into your Confluence page. The box will display search results as you type.
Children Display the macro displays all affilated pages to the page where it is used, or from the specified specific section and page. I try to use it on top-level pages to set up easy navigation and nesting of pages.
Table of Contents macro creates a table of contents for the current page based on the page headers.
Page Tree — macro displays a tree of pages. You can customize the page for which you want to display the tree, limits, sorting and adding a search string.
Anchor allows you to create anchors within a page that can be hyperlinked.
How to customize:
- Insert the Anchor macro in the location you want to reference and come up with a name.
- Click “Insert Link” in the top bar to link to the anchor.
- Specify the anchor name with # if you want a link to an anchor within the same page.
- Specify the page and anchor name via # in the Link block to link to the anchor of another page in the same space.
- Specify in the Link block the key of the other space, a colon through the page name and anchors with # to link to the page from the other space. For example: MobileCore: Vacation Calendar#My Anchor.
- Specify a link to the page in the Link block by adding the syntax #:~:text= and a specific word or phrase to link to the specific word or phrase. For example: https://wiki.ru/pages/viewpage.action?pageId=250575000#:~:text=How to customize.
How to set up macro reports
Report macros help you create different calendars, build reports on page properties, import data and convert to a report.
Most of the macros we’ve dealt with can be in several types at the same time. In this section, let’s look at just one type of macro.
Page Properties and Page Properties Report. You can put anything in the Page Properties macro, but hide the macro itself and the content will be visible only in edit mode.
You can use the data from the Page properties macro to make a Page properties report. This macro collects all information about the properties of specific pages and displays it in a table.
How to customize macros using CSS
To build a rocket in your documentation, use the CSS style. This is a more advanced level, and if you don’t want to bother too much, you can build a simpler rocket using the macros we discussed earlier.
What macros CSS uses:
- Div is a block element. It is needed to select a fragment in the document that you want to change. To access it, specify the class or ID attribute with the selector name.
- CSS Stylesheet — created to write CSS styling and refer to the classes created.
- Clickable — helps you create clickable blocks.
Let’s create a clickable block with a title and an image for the example:
- Create a macro with the class test-component-panel. In the macro you can set the name, style and language of the code, but we will limit ourselves to the default settings.
- Add a new Clickable macro inside the class to make our settings area clickable. In it specify a link to go to the required page.
- Add new classes: for example, with size, color, indentation settings, or with picture insertion.
- Insert the CSS Stylesheet macro to make our rocket take off. Add CSS Stylesheet to CSS Stylesheet and the data from the code will access our classes and populate the data.
More interesting macros!
A few curious macros that didn’t fit a particular type, but are worth paying attention to.
Vote and Survey are macros for creating polls. Above we have already discussed a similar Forms macro that helps to create polls, these same macros will help you to create polls for your team.
Progress Bar Container and Progress Bar — you can create a progress bar for any needs. For example, a june who is onboarding a newbie has joined the team: you can use this macro to formalize his progress.
How to customize the Progress Bar Container:
- Insert the Progress Bar Container macro and customize. Specify the current progress step number, hint text when hovering over the progress bar, or set the color using CSS styling.
- Place Progress Bar macros in the container. Depending on how many macros are added, there will be as many progress steps. In them you can customize the step name and the URL for the hyperlink when you tap on the step.
Lock content — prohibit specific users or groups from viewing or modifying the page.
Blog Posts — macro will display all blog entries in your space’s blog.
Conclusion
It is important to pay special attention to the design of any documentation. Macros should be used in moderation and not to cover all documentation with them like a Christmas tree.
I hope this article will help you design a cool and handy documentation that will gather a lot of likes from your colleagues. I will be glad to get your feedback!
And be sure to write what Confluence features you’d like to learn more about. In Part 2, we’ll talk about page layout, tags, and templates. Stay tuned!
