Apples and Oranges: Seven Reasons Why Confluence and DITA Are Hard to Compare
When it comes to finding an authoring and single-source publishing environment, often Wiki-based documentation (e.g. with Atlassian Confluence) and structured XML authoring (usually with DITA) are compared.
This blogpost outlines the different use cases of wiki-based documentation versus XML-enabled structured authoring. But there's also one thing both approaches have in common.I recently stumbled across a very interesting blog post by Antti Hietala. He writes:
Any unnecessary obstacles such as forced structure (DITA) or formatting conventions (Markdown) stand in the way of getting content written. A casual user who wants to contribute should be able to just start typing. I will take care of the formalities. Wiki is great for that. Collaboration and ease of use are killer features that make an open documentation project work.
This article, and the really valuable discussion in our blog about structured authoring and DITA, made me think about the contrasting approaches taken by DITA and wiki-based documentation with Atlassian Confluence and the Scroll Content Management add-ons. They differ in several ways, so maybe we're comparing apples to oranges. In the discussion of simple vs. complex tools, let's focus on the use cases, and consider the fundamental differences between DITA's and Confluence's approach.
#1 Different Priorities and Approaches
DITA: The Darwin Information Typing Architecture is primarily employed to structure content, re-use it on any level, and publish it. Simplicity and ease of use have never been a priority for the DITA environment. The only initiative with this goal that I'm aware of is the Lightweight DITA project, which is about reducing the element catalog to a reasonable number of structure items.
Confluence: The main motivation for using this collaboration platform is completely different. The fact is, people really do go ahead and use it, because it’s so simple and intuitive – and because it’s probably already in place. That makes it ideal for casual users wanting to create and share content in the wiki. All they need to do is start typing.
Certain content management features beyond basic content re-use are available only as add-on for Confluence, e.g. to create pages in multiple languages or to manage multiple versions and variants. The same applies to structured authoring and single-source publishing to multiple output formats.
#2 Different User Groups and Application Scopes
DITA: In most cases, DITA content applications are only used by technical writers. That’s why their focus is managing technical documentation with DITA, and not much other use cases. So DITA authoring environments are specialist applications for technical communications. Only technical writers are familiar with this topic complex – DITA maps, publication scripts, DTDs, and so forth.
Confluence: In contrast, most Confluence authors have no technical writing background. They use this platform for many purposes: as an intranet, a knowledge base, or to collaborate with customers and partners. Confluence makes it easy to involve all participants in the content creation and distribution process. If they have the right permissions, they can edit, comment and share content. And more and more organizations are now beginning to use Confluence for managing technical documentation.
#3 Different User Skill Sets
DITA: All employees involved in the DITA-based content lifecycle need sufficient XML skills and in-depth knowledge of DITA to be productive writers.
Furthermore, DITA is often embedded in a content management system or another tool chain that requires configuration and extensive customization in advance.
Confluence: With this enterprise wiki, no specific knowledge or technology skills are needed to create content of any kind. Confluence has a rich text editor for pages and blogposts that will be familiar to anyone who’s ever used a word processor.
Technical writers who work with Confluence don’t need any XML skills or knowledge of DITA. What’s more, they often don’t need to set up the system, because Confluence has already been employed for some time as a company-wide intranet platform. This means they can concentrate simply on writing and improving the quality of their content.
#4 Different Approaches To Quality Assurance and Content Lifecycle Workflows
DITA: All changes made during the content review and approval process need to be performed in the DITA environment itself. But subject-matter experts and editors often don’t “speak” XML, so the content often needs to be exported for review. And all change requests submitted in the form of Word and PDF documents, or sometimes even as a hard copy, have to be re-imported manually into the DITA environment – a huge bottleneck. That’s why Tom Johnson suggests exporting DITA content to Confluence and letting subject matter experts add comments (and where necessary, edit the content) there.
Confluence: Walking the 'wiki way’ means that everyone involved in the content lifecycle is invited to contribute and to improve existing content. This crowd-sourcing approach for complete, actual and accurate content works pretty well – not only for Wikipedia. In addition to this "ex-post” approach, there are wiki gardeners helping to keep everything neat and tidy. And if a stricter process is needed, there are add-ons available for Confluence that introduce customizable approval workflows and release management.
Frequently, subject-matter experts are already Confluence users (who may have corresponding approval permissions). Because everyone is literally working on the same page, it is not necessary to export content from Confluence just to be reviewed. Nor does the reviewed content need to be re-imported afterwards. So users can offer feedback easier and faster, and exporting is not a key element of the quality assurance workflow. Nevertheless, advanced content export is available for Confluence via add-ons.
#5 Different Content Distribution and Strategy
DITA: Besides the DITA user group, no-one else in the organization is usually able to access the valuable information assets maintained in the DITA content silo. In some cases, that could be a good thing, but generally speaking it is not, because it hinders technical communicators from playing the vital role they should be playing in their organizations.
On the other hand, DITA-XML is a standardized data format that could be exchanged with suppliers, contractors and partners – in theory, at least.
Confluence: The wiki can serve as a “single source” for any corporate content. As part of a unified content strategy, you can even invite customers, partners, contractors and suppliers to collaborate via Confluence. Permission restrictions ensure that external parties can only view content intended for the respective target group or even for anonymous users. And of course, Confluence content can be published into numerous formats, too.
#6 Different Information Architectures
DITA: This architecture is not merely a technology; it also enforces topic-oriented writing. Every topic should be a piece of content that is about a specific subject, has an identifiable purpose, and can stand alone. Typically, a DITA topic is equivalent to one XML document. DITA offers default topic types (such as task, concept and reference) to help authors create a consistent documentation structure.
Confluence: Content in Confluence resides on pages. And by default, Confluence doesn’t restrict what can go on a page. So it can cover one or several topics. And in fact, nothing compels you to write in a topic-oriented manner at all. That’s because Confluence is not a specialized help authoring tool. As a born-and-raised collaboration platform, it needs to adapt to more use cases for content creation and distribution than DITA. By default, it also poses no restrictions on topic or page types. But at the same time, Confluence can be equipped with custom page template and structuring macros that allow users to write about topics of specific kinds.
#7 Different Approaches To Formatting and Structuring
DITA: With structured DITA authoring, authors have complete control over a topic's inner XML element structure. If you want to create a list that is broken up with a result statement, some sub-bullets, and maybe a screenshot, you can do so by re-arranging elements (as long as it doesn’t contravene DITA's XML structure definition).
Confluence: Confluence’s rich text page editor takes a completely different approach. It hides tags and element cascading rules from users, allowing them to focus on the content. This means that its structuring capabilities – as described in the list example above – are limited. So topics that need very complex or cascaded structures may not be suitable for a Confluence page at all.
But this may not actually be a drawback; Instead, a very complex topic structure indicates that it might be a good idea to rethink that complex content structure and simplify it – for the author’s and the reader’s sake.
One Thing Both Have In Common
After this lengthy (but probably not complete) description of the differences between the DITA and the Confluence approach, let me conclude with an inconvenient truth that applies to both systems: Neither DITA nor Confluence guarantee their authors consistent content and structure by default.
The DITA authoring environment provides a list of elements that you are allowed to use in the specified context, and forbidden to use in others. Yet, DITA still gives authors more freedom than is reasonable in many cases. For example, a valid DITA topic could consist of a subtitle element that contains unordered and ordered lists, figures and images. Stupid? Yes. Invalid? No!
A Necessity In Any Case: Authoring Guidelines
The only solution to this structure-without-structure dilemma is authoring guidelines that define how to apply DITA structures in a consistent and reasonable manner. A style guide should also instruct content managers to re-use content and build consistent document structures. This is what Mark Baker terms a 'rhetorical structure'. It allows both the writer and the reader to perform at a more consistent level of content quality. And while these kind of issues primarily apply to DITA, they apply to Confluence content in exactly the same way.
The same is true of wording, terminology and style rules, which can be enforced by a content optimization platform such as Acrolinx. It gives authors guidance on how to write in a more consistent way and improve the linguistic quality of their content. Here’s the good news: Acrolinx is not only available for many XML editors, but also as an add-on to Confluence.
A unified content strategy is definitely the key to success with both approaches whether you opt for DITA, Confluence, or any other authoring tool, technology or platform. Far more important than the underlying content storage format is the suitability of your use case. You need to choose between a complex, XML-driven tool limited to technical documentation, or a collaborative wiki approach, open to everyone involved, and simple to use.
Development and TechnologyUp to Eleven - Amplify Your Development Setup for Atlassian Server and Data Center