When it comes to documenting a sizeable multi-component software project, documentarians want to make the process of keeping the knowledge base up-to-date as efficient as possible.
Designing documentation architecture with content reusability in mind can significantly increase the speed of creating new and reduce the time for updating existent articles.
In this post, we will take a look at four types of reusable content in Confluence, which quickly positioned themselves favorably at our company, namely:
- Templates
- Atomic elements
- Parts of articles
- Generalized articles
Templates
A template is a skeleton upon which multiple articles can be created. Templates serve three purposes:
- unifying documentation according to the standards accepted at your company;
- simplifying the process of documenting providing a particular structure to follow;
- engaging Developers, QAs, and other team members in writing documentation.
Confluence has a wide range of built-in templates for different purposes, but you can also create custom templates that reflect your target audience’s specific interests.
Practical case
Our company works on a software project that implements microservices architecture, and we need to have documentation for each microservice.
Before creating documentation for each particular item, we asked our Developers what they expected to see in the articles — the essential information they needed to know about a microservice. After interviewing, we gathered all the requirements into the following template:
With this template, not only our Technical writers but also Developers can create documentation on microservices:
Tips
- Placeholders in templates
In placeholders, you can put instructions on filling in a particular template section. - Filling out sections in a template
A template may contain a section that implies extensive details
(for example, API specifications or Business logic sections in our template). In this case, it’s better to write a separate article revealing the topic. When the piece is ready, you can give a link to it in the article created from the template:
Templates have a downside — if you modify a template, those articles created from its previous version won’t be updated automatically. However, they still save a lot of time spent on planning documentation.
Atomic elements
Atomic elements are single words, phrases, or screenshots that appear in multiple articles throughout the documentation.
The idea of reusing here implies that there is an article where you first introduce an atomic element (origin). Then you create referenced copies of the element (clones) in other articles that should have the same information. It seems like duplicating content but with one game-changing advantage. If this element changes in future, you only need to update the origin, and all the clones will be updated automatically.
In Confluence, there are two macros for reusing atomic elements —
Excerpt and Excerpt Include.
Practical case
There are many microservices in our project’s architecture. Therefore, Developers need to have a page (an index) listing all the existing microservices together with the following details for each one:
- a link to a service’s GitLab repository
- a list of IP addresses where the service is hosted
- a link to a Jenkins job used for deployment
When developing the architecture for this documentation, we agreed that
- this index page will contain original information on these three points (with concrete values and links) for each microservice
(in Excerpt macros); - in the articles dedicated to each service in particular, we will create clones of those original content elements (in Except Include macros).
Let’s get to implementation!
We create a page called Microservices. Index with a structure reflecting all three requested points:
❓ You may ask why not use a table since it would be more convenient to maintain and probably look better. The point is that this Excerpt macro that we are going to leverage can’t be inserted into a table column.
Instead of {service_name}, we put a name of a specific microservice linking it to the corresponding documentation (if it exists).
Using a concrete example — email-sender-service,— we fill in the three columns step by step:
- in the column Hosting address, we create an Excerpt macro;
- name it email-sender_host_addresses;
- put the actual host addresses (provided by our System administrators) into the macro:
4. in the column GitLab repository, we create an Excerpt macro;
5. name it email-sender_gitlab_repository;
6. put the link to the repository into the macro:
7. in the column Jenkins job, we create an Excerpt macro and repeat steps 5 and 6 for it changing the macro’s name to email-sender-service_deploy and inserting a link to the corresponding Jenkins job:
At this point, we have one microservice with all the needed original links on the index page. It’s time to create clones in the article we created earlier — in section Templates.
We will create a clone of the link to the GitLab repository. The rest of the origins can be cloned the same way, and we won’t explain them here.
So, we open our article about email-sender-service for editing and perform the following steps:
- in the row Repository, we create an Excerpt Include macro;
- in the setup panel, we configure the parameters:
- Page Containing the Excerpt — our index page Microservices. Index;
- Excerpt Name — email-sender_gitlab_repository;
- Remove Surrounding Panel — checked (just to make it look good);
3. click on the Preview icon to make sure that the correct link was cloned;
4. click on the button Save:
Now, we can say that we smartly reused this atomic element — the GitLab repository link. If it changes, we only need to edit the Excerpt macro on the Microservices. Index page. In the rest of the articles where you cloned the original link, clones will be updated automatically.
It may seem quite a laborious task, but it will definitely pay off in the future, saving you time and nerve cells.
Tips
- A single page containing similar origins
It’s much easier to change original atomic elements when you know where they are. Create an agreement within the company that original elements should be introduced on such index pages so that it is intuitively clear where to go to make changes. - Names of Excerpts macros
A name of an Excerpt macro that contains an origin atomic element should be precise and reflect the essence of the element. If you have a link to a particular service’s code repository as your atomic element, name the corresponding Excerpt macro something like service1_repository_link, not just exc1.
Parts of articles
Similar to atomic elements, you can reuse parts of articles using Excerpt and Excerpt Include Confluence macros.
Practical case
Suppose we have a microservice —job-recommendation-service — responsible for generating recommendations to users differently depending on the user’s activity on the site:
- recommendations can be generated by schedule, taking into account all the vacancies that the user applied for during the last 7 days;
- recommendations can be generated by the trigger when the user applies for any vacancy on the site.
The complicated algorithm behind the microservice implies 5 steps, among which the first step is the same, but the other four ones differ.
When creating documentation on the microservice’s business logic, we wrote two articles on both scenarios. But we decided to put this first step into the Excerpt macro in the first article and reuse it in the second one:
❗ Here, we took a little risk because we don’t know whether this first step changes for one of the scenarios. As of now, reuse works well, but if, in future, this first step is adjusted for the first scenario, we will have to remove reusability out of the picture for this case.
Tips
- Reuse only single-subject content parts
If you want to reuse content that takes more than one line, make sure you won’t duplicate irrelevant information. You don’t want to confuse readers with extra details they don’t expect to see. - Too large content parts
I wouldn’t recommend reusing parts of articles that take more than half of a page. When you insert such a large volume of text, it is not convenient anymore and doesn’t justify the effort. - The nature of change of the reusable part
Like in our example, consider the risks of reusing parts of the content. If you know that this part will change in the foreseeable future, it’s better not to apply reusability for the case.
Generalized articles
By a generalized article, I mean an instructional how-to guide that explains a particular process in general without providing concrete names, links, or other specific details.
In this case, we use other Confluence macros — Include Page and Expand.
The following Practical case explains the approach.
Practical case
Almost all microservices in our project are deployed according to the blue/green technique. Developers and QAs use several instruments (Jenkins, Consul, Kibana) to deploy a service, let a portion of traffic to the newly deployed functionality, track errors, and finally let the whole traffic to the new version of the service.
While the algorithm for deployment is the same, there are multiple variables in the process:
- names of Jenkins jobs used for deployment of different microservices;
- links to those Jenkins jobs;
- links to Kibana to track errors for a particular microservice;
- etc.
So, here is how we built our documentation on deployment:
- We created general instructions on how to deploy a microservice using the blue/green technique. In this instructions, we gave links to the instruments used for deployment, but these links direct readers to the main page instead of a specific section.
- For each microservice, we created a separate article on its deployment.
This article contains concrete names and related links used for this particular microservice, as well as the general instruction hidden in the Expand macro:
🟢 What we gained
First, we don’t need to write a separate detailed article on deployment for every single service we have.
Second, our readers don’t have to switch between several browser tabs to get all the necessary information on deployment.
Third, the content organization is neat and convenient.
Tips
- When to use this type of reusability
Reusing a whole article is justified when it has multiple structural elements in it (tables, info panels, lists). Although, Excerpt macro handles different types of structural elements pretty well, I find it more convenient to work with a page when it comes to profound guides.
Reusability is one of the most powerful content features. As we can see, reusing content can simplify the process of writing documentation and improve the user experience. Readers don’t have to click on links and navigate multiple articles in different browser tabs, and documentarians don’t have to worry about making changes to the content.
So, planning your documentation with reusability in mind will benefit both writers and readers.
Shall you have any questions, feel free to ask me via email — rinagreen090296@gmail.com
P.S.: Useful materials
📃Content Reuse — The art of not writing the same shit over and over again!
