Confluence is much more than a Wiki. As you become a power user of Confluence, there are many macros that can help simplify the process of writing better documents.
Take for example, the Comala metadata plugin (free plugin for Confluence server). By providing a set of macros that allows you to easily define your metadata, and then refer to it, Comala has long been a vital part of any Confluence (server) installation.
The following two examples illustrate how metadata can make your quality process documents both easier to write and maintain.
Use Case #1: Define Metadata once & use it multiple times
Say that you are writing a ten-step work instruction that explains a multistep process, where there’s always a sign-off at the end of each instruction, i.e: “Please sign electronically, providing your username and password.”
The traditional way to write this is to copy and paste the same sentence, ten times.
Now, imagine that you need to change the above to read, “Please sign this step providing your digital signature.” Obviously you would like that adjustment to be reflected everywhere where the previous electronic signature instruction was mentioned before. Theoretically you could do an automatic replace across all instances, but what if everywhere the sentence appears isn’t exactly the same? For example, if one has an accidental extra blank, then an automatic replace would not work. Furthermore, if the person who changes the text is less familiar with the instructions and is not aware that this sentence appears at the end of each one, then it’s entirely possible that he might change the first occurrence and forget to address the others.
That’s exactly where metadata comes into play:
- Step 1: Using the macro Metadata list, define a metadata: signature text =Please sign this step providing your digital signature (Tick the “hide” box so it’s concealed when the page is in “View.”)
- Step 2: Each time you need the signature instruction to appear, use the Metadata value macro, fetching the metadata’s “signature text” from @self (the same page).
- Step 3: Publish the page. Confluence will render the page as you want, with the correct signature text appearing each time the metadata is called upon.
Using the macro Metadata list, define a metadata: signature text =Please sign this step providing your digital signature (Tick the “hide” box so it’s concealed when the page is in “View.”)
Each time you need the signature instruction to appear, use the Metadata value macro, fetching the metadata’s “signature text” from @self (the same page).
All it takes is those three simple steps when your signature text needs updating, and you can change it in a single location — at the metadata definition — guaranteeing that the new text appears consistently throughout the document.
ADVANCED OPTION: Metadata can be used across pages, so you can follow the same process to define something only once but have it appear in multiple locations. For example, you can define the name of your product in metadata, and if ever the product name ever changes, then you’d only need to replace it once for it to appear everywhere you need it to throughout your document.
Use Case #2: Make it easy to change organizational responsibilities
This example is particularly powerful when writing Standard Operation Procedures (SOPs).
Very often a procedure has certain role within the context of an organizational responsibility, for example, a recruitment procedure will have a role for “recruitment manager.” This person will have responsibilities including finalizing job descriptions, publicizing employment opportunities, preparing employee contracts, and so on.
Who the recruitment manager is within the organization may change over time. For example, when the organization is very small, the job title may be “Office Manager.” Later on, it may be assigned to other positions, such as the “HR manager,” or “Talent Champion,” and so on. None of these title changes fundamentally alter the procedure; however, it is easier to read if the correct title is used through the document. And so referring to the correct title (i.e. “HR manager”) is clearer and less ambiguous then referring to the role (“recruitment manager”). Metadata once again is the secret to automatically updating each procedure in multiple locations throughout a given document whenever there is an organizational change:
- Step 1: Using the macro Metadata list, define a metadata: recruitment manager = HR Manager (Tick the “hide” box so it’s concealed when the page is in “View.”)
- Step 2: Each time you need the correct title to appear, use the Metadata value macro, fetching the metadata, “recruitment manager” from @self (the same page).
- Step 3: Publish the page. Confluence will render the page as you want, and the “HR manager” text string will appear each time the metadata is called upon.
Engineering your procedures in Confluence is a simple – and sanity-saving – step. All it takes is installing a timesaving plugin like Comala metadata, and keeping your document up to date is a snap.
