Structured Authoring for Confluence
Comment
Structured Authoring for Confluence
This blog post explains how you can create semantic structures for Confluence content.
We recently held our first K15t ShipIt Day, a hackathon and ideas competition. As a former tech writer, my idea was to add more structure and semantics to the Atlassian Confluence enterprise wiki.
In most cases, Confluence is the go-to solution for easy content creation. But in many techcomm environments, it’s vital to create and maintain heavily structured content – and to write in a consistent style.
There is constant debate about the merits of both complex (e.g. DITA) and simple tools (e.g. wikis) – and how best to reduce the complexity of authoring environments. Here’s how to use Confluence to combine structured authoring with the wiki-based approach to documentation.
Why Standardization and Structured Authoring?
You can enhance your technical documentation by applying standards such as DITA, or by using writing techniques and standardization methodologies such as Information Mapping, Funktionsdesign, or topic-based approaches to writing.
As a result, your content becomes more consistent and easier to re-use. What’s more, it’s clearer, more concise and more closely focused on the target audience.
These techniques and approaches are independent of the authoring tool, but they often align neatly with the underlying technology – such as Microsoft Word and custom semantically-defined styles, and XML applications that ensure standardized content structures, defined with cascading elements.
Confluence's Strengths and Structuring Abilities
Confluence is a great tool for writing, managing and publishing documentation. More content management and single-source publishing functionality is being added all the time, but it still lacks structuring features for semantic content markup. These structural elements could be Q&A sets, glossary entries or a parameter reference that requires a standardized skeleton and enforces a consistent writing style.
Confluence already offers a few content markup features:
- Rich formatting for text (lists, tables, bold/italic etc.) from the Confluence editor’s toolbar
- Some semantic elements for creating notes, tips, warnings or code blocks – using macros
- Page templates may contain a predefined arrangement of content elements, such as macros and placeholder text blocks.
Confluence also differentiates between page titles (which specify the page topic) and the page content itself. This functionality is quite extensive for a collaboration tool, but some technical writing teams may find it doesn’t offer enough in the way of structuring rules and authoring guidance.
Bringing Structured Authoring to Confluence
One way to add structure to a wiki could be to imitate technologies and standards such as DITA and other structured XML applications. This usually results in lots of forms being developed.
We’ve been there, tried that at K15t Software. For small-scale applications, it may be an effective way to ensure consistent content structures. But for larger information structures – such as those required for technical documentation – we soon realized that we’d have to find the right balance between giving our writers freedom to create content, and providing clearly defined structures.
After all, Confluence is an enterprise wiki platform that’s intended to provide a great WYSIWYG graphical editor – one that anyone in the organization can pick up and use to write and share content.
More Guidance, Fewer Constraints
Instead of limiting your authors’ freedom to create awesome content, it’s better to give them all the structuring and writing guidance they need – and then let them decide if a proposed structure should be used for a particular case, or if a slight deviation from the standard would make more sense.
The best solution is to utilize Confluence’s existing functionality (macros, templates/blueprints, plug-ins), and extend your Confluence documentation space with corporate-specific structures and semantics. This combines the pros of an enterprise wiki with structured writing techniques.
Here’s how to structure content and standardize authoring in Confluence:
- Use Confluence macros that provide the required semantic elements and define the appearance of each structural element (e.g. as a highlighted box, as a list, or just as plain text). These macros could include a short description of how to use the element, and a link to the authoring guidelines for that element.
- Define and use custom page templates (or Confluence Blueprints) for each content type. Each template contains your Confluence macros in the desired order and hierarchy.
- Add placeholder texts to embed pre-defined wording and authoring guidelines into page templates.
- Create authoring guidelines that contain a detailed and structured definition of each structural element, and explain how and when to use it.
- Utilize a solution that automatically checks the structure of each page and warns authors if the hierarchy and order contradicts the guidelines within the template.
- Finally, use the Acrolinx language optimization platform – brought to Confluence by Scroll Acrolinx Connector. This tool checks your terminology, tone, and writing style automatically.
How to Bring Structured Authoring to Confluence
If Confluence is your documentation platform and you reach a point where you really need to structure and standardize your content, I recommend considering the following steps:
Step 1: Find a strategy and methodology
Understand your audiences and the creators of your Confluence-based content, and develop a content strategy. This is key to creating a structure and defining standards for your content. Popular methodologies include Funktionsdesign, Information Mapping, and ARAKonzept.
Step 2: Define standardization rules and a structure
A content analysis workshop will help you develop a standard that best fits your communication needs. For this step, you need to define relevant element types for your Confluence content. You should also create authoring guidelines that specify usage, wording and the formatting of each element (Confluence is a great place to do this, by the way).
Step 3: Create structures and templates
Arrange your content elements in standardized structures for each content type, e.g. for concept, task, and reference topics. The structure elements are cascaded in the desired sequence and hierarchy. You can also embed wording templates and authoring guidelines to ensure a consistent writing style when producing new content assets.
Step 4: Make it available to all Confluence authors
Build a Confluence plug-in that delivers all of your standardization structures to your Confluence platform and authors. This plug-in should contain custom macros for semantic structures and page templates (or blueprints).
Conclusion and Outlook
As you can see, it’s perfectly possible to add structure to the Confluence content platform. This might not quite the same as a technology-driven XML approach that enables you to retrieve and recombine sections of content using tag names. However, it helps your authors by providing a content structure and giving them all the guidance they need.
Content structures have to be tailored to the needs of authors and readers anyway, which makes this approach even more appropriate. Now, you need to develop a standardized structure for your documentation – so your technical writers and other authors can produce first-class content every time.
