Two major Confluence problems: poor content re-use and lack of wiki markup

by Tom Johnson on Sep 24, 2014
categories: dita wikis

The other day I tweeted about a brief frustration with Confluence:

And a couple of people asked me for a post with more detail.

I didn't plan to provide any more detail, but today as I was making a few edits on Confluence to fix some last content before migrating it to DITA, I got somewhat frustrated and realized it might be helpful to some technical writers evaluating tech comm platforms to have more insight about why Confluence kinda sucks for tech comm authoring, particularly when it comes to re-use scenarios. So here you go.

Re-use is broken

Confluence works well as an internal wiki when you don't need to re-use content. If you have a content re-use scenario, however, watch out.

The basic problem stems from the fact that Confluence puts both source files and production files on the same platform. This creates difficulties with re-use.

For example, let's say you have a section you want to re-use in two places. We'll call this re-used section "Block A." You probably have a page called “Re-used Blocks” that has Block A, Block B, Block C, and so on, representing other re-used components.

Re-used Blocks
- Block A
- Block B
- Block C
- Block D

You want to insert these blocks into various pages:

Page for Audience 1
  - Block A
Page for Audience 2
  - Block A

The recommended approach is to store your Re-used Blocks page (or "inclusions library") either outside your space navigation (one level up) or in another space. If you store your Re-used Blocks page one level above your navigation tree, no one will be able to see the page. The way you access it is by browsing your space's pages as a space admin.

In this limbo space, no one can see Re-used block A if they just look at the space's navigation. This is good -- you don't want people to find the page because it doesn't make any sense to a regular user since the blocks are all out of context. It just has Block A, B, C, and D stacked on top of each other.

Now on your Page for Audience 1, you might use the popular multiexcerpt include macro to embed Block A. Sounds okay, right? The Re-used Blocks page is out of sight, right? And you've transcluded content from it to a page users see.

Wrong. When a user searches for Block A, the search returns the Re-used Blocks page as the top result, because that's where the content is. The Page for Audience 1 doesn't even appear in the search results, because all it has is a little macro placeholder. The placeholder means nothing to the search engine.

Difficulty in seeing blocks

With the multiexcerpt plugin, it's also difficult to see the various block names. Let's say you want to edit the Page for Audience 1. This page might contain the following blocks:

Page for Audience 1
- Block A
- Block B
- Block C
- Block D

Now you need to make an edit to one of the sections. When you edit the page, surprise, you can't see the name of any of the blocks. It looks like this:

Page for Audience 1
- Block
- Block
- Block
- Block

You have to click Edit on each one to see the re-usable block name. Additionally, with the multi-excerpt macro, there's an option to "Go to included page." This means go to the source page that was transcluded here. But this button doesn't work with the macro. You get a Page Not Found error (at least I do).

Instead of using the multi-excerpt include plugin, suppose you use the default re-use macro for Confluence (called "excerpt include"). If so, you must create a separate page for each of your blocks. So rather than having Block A, Block B, Block C, and Block D all on the same page (multiple excerpts on a page), you have a page for Block A, a page for Block B, a page for Block C, and a page for Block D.

Those are a lot of individual pages for each of your re-used components. (Thankfully if you're using excerpt include, you can actually see the block names without editing them.)

Whatever macro you use, the method is just clunky. You can't do any kind of conditionalizing of content. For example, suppose two pages are 99 percent similar and just 1 percent different. In DITA, you could create one page and add an attribute to the element that is different, like this:

Page for Audience 1 and 2

Paragraph 1

Paragraph 2

Paragraph 3

Paragraph 4a

Paragraph 4b

Then when you transform your content into the output for Audience 1, Paragraph 4b can be excluded. And vice versa for Audience 2.

You can't conditionalize content in Confluence. There is a plugin called Scroll Versions from K15t that allows you to create variants, and then provides a selector menu so that users can choose the variant they want to see while viewing the page. But you can't automate the variant based on login permissions. Audience 1 would need to manually select Audience 1 from a (rather subtle) drop-down menu.

Because there isn't any conditionalization, you have to create an invisible page (the "Re-used Blocks" page) that has re-usable blocks like this:

Re-used Blocks
- Block A
- Block B
- Block C
- Block D1
- Block D2

Then you create two pages in your regular space area and insert the blocks you want, like this:

Page for Audience 1
- Block A: Paragraph 1
- Block B: Paragraph 2
- Block C: Paragraph 3
- Block D1: Paragraph 4a

Page for Audience 2
- Block A: Paragraph 1
- Block B: Paragraph 2
- Block C: Paragraph 3
- Block D2: Paragraph 4b

As a result, with re-use scenarios, you have a lot of blocks that you're embedding into different pages. When you're looking at your Re-used Blocks page, you can't actually tell which pages the blocks are transcluded into. It could be one; it could be twenty. When you do a search for the block, you end up right back on the same page you're looking at!

By resorting to excerpt or multiexcerpt include plugins, you essentially hollow out your pages, making it difficult to find anything.

No wiki markup

The second major problem with Confluence is lack of wiki markup. When you're writing content, you can't use source code. Well, technically you can insert wiki markup, but just once, because as soon as you save it, the wiki markup gets converted to HTML syntax with a bunch of proprietary custom Confluence tags. You can never go back to the wiki markup view.

Let's say you're making a list of steps that is broken up with result statements, images, code blocks, and other details. How do you insert content between list items?

First, you make all the list items you need. Then you go to a place where you want to insert content between list items. Here you do a soft-return by pressing Ctrl+ Enter to create a line break. Then you press Ctrl+Enter again to create some spaces between the images or other content you've inserted. Lots of soft-returns (or whatever you like to call Ctrl+Enter).

Look out if you have to suddenly edit your list. Suppose you want to move a screenshot to a previous step, or eliminate a step, or do any other tweaking. Get ready for quirky ride of formatting hell that will make you actually long for Microsoft Word. You'll probably have to go into source view to try to find and fix some tag that got misapplied. Even when you fix it, the spacing can still be wonky.

Today when I went into source view to troubleshoot, I discovered the following code:

The  methodName  method invokes the gizmo. Add this method in your app where you want to load the gizmo.

I'm not making this up.

Now, span tags aren't so hard to strip out. But if you ever want to migrate your content out of Confluence, you'll be saddled with all kinds of Confluence markup integrated tightly into your content. For example, here's what a code block looks like:


       
 here's my code...
 
     

The content is riddled with tags like this for every macro. Even when the browser renders the wiki content into HTML, it keeps all the macro tags.

Despite all this...

If you're really bent on using Confluence for technical writing, do check out my Re-use Strategies for Confluence post. (I'm a lot nicer in that post -- just don't read the comment thread.)

Despite these limitations with re-use and wiki markup, Confluence is a good tool for an internal collaboration when you have no re-use needs and when each contributor prefers a Microsoft Word-like experience in writing content. In all likelihood, Atlassian is probably hitting its target audience. But it's not a tool many technical writers will enjoy. In fact, it will probably make you want to pull your hair out.

If you really need a wiki, I recommend using the open source platform Mediawiki. But I don't actually recommend wikis. If you want to know why, see my short post My journey to and from wikis.

About Tom Johnson

Tom Johnson

I'm an API technical writer based in the Seattle area. On this blog, I write about topics related to technical writing and communication — such as software documentation, API documentation, AI, information architecture, content strategy, writing processes, plain language, tech comm careers, and more. Check out my API documentation course if you're looking for more info about documenting APIs. Or see my posts on AI and AI course section for more on the latest in AI and tech comm.

If you're a technical writer and want to keep on top of the latest trends in the tech comm, be sure to subscribe to email updates below. You can also learn more about me or contact me. Finally, note that the opinions I express on my blog are my own points of view, not that of my employer.

M ↓   Markdown
D
David Carrington Jr.
0 points
8 years ago

I know it's an old post, but I've only been introduced to the shit-show that is Confluence in the last year. How about: no WYSIWYG, crippled text search, no resizing table columns on the fly, and saving your work is now a part-time job. I feel like I've regressed to 1989.

Oh, and when you get edits from your reviewers...30-40 comments each helpfully designated by page number. Try explaining to your reviewers help that you actually have no idea what "page" anything is in your source file.

?
Anonymous
0 points
10 years ago

My company has used confluence for a "knowledgebase" (notes and internal documentation) for 10 years or so. We still have a (many years out of date) installation on one of our servers, and a couple of cloud instances for some newer stuff.

They used to give you access to the source markup. Our old installed version still lets you switch between source markup, rich edit, and preview tabs. They've been working on the rich text editor since we first started using, and have yet to get it right. In our old installed version, you inevitably have to go into the source to fix things when they get screwed up, or just to do thing in the first place as something are just easier that way.

However switching back and forth, it inevitable screws something up. The only safe way is to never edit with their rich text editor once you've started on editing the source.

So I assume they "fixed" their inablility to get that right, by just taking away the ability to switch back and forth. But it boggles my mind that they would do this when they clearly can't get the rich editor right either.

I always end up with pages that have weird formatting going on that is completely unfixable or inspectable in the editor. A bit of text will be indented yet no buttons get enabled when I click on it, including the outdent button, so there is no way to fix the indenting. Lines have different space between them than other again for no reason the editor will let me see or change. Some bits of text that look perfectly plain and again provoke no toolbar reaction, get rendered into icons while other identical bits of text do not. It fills me with rage.

?
Anonymous
0 points
10 years ago

Tom, it would seem that you can get excerpts to be searchable within articles...it requires another plug in though.https://ffeathers.wordpress.com/201...

Hopefully this solution works with multiexcerpt content too.

?
Anonymous
0 points
10 years ago

Thanks for the tip.

?
Anonymous
0 points
11 years ago

I have to agree with Tom - I don't like Confluence as a documentation tool much at all. I've had to work with Confluence on Demand lately, which admittedly is a really stripped down version...but so much stripped down that it is barely usable. There are so many annoying formatting issues that you can't put right because there is no access to the source code (the plug in doesn't work for On Demand) and there's no access to a css style sheet either. I have used the full product, which was better, but I'd read about the problems with content re-use, and even the use of multiple 'excerpts' requires a paid-for plug in. The amount of plug-ins needed makes it more costly than it first looks.

Given the choice, I would use Flare or Robohelp over it every time.

H
Hemal Patel
0 points
9 years ago

Looks like you have read my mind! I am working with Confluence lately. I so agree that the usage has a lot of limitation. However, I do understand the other side of the coin too. When I see the developers penning down their part of documentation, there's no other tool better than Confluence. All they need is a common platter to access, and Wiki is a way to go.

However, as a technical writer, it's tough to maintain single sourcing, conditional build tagging, exporting to PDF/Word, and to an extent the look-n-feel too.

?
Anonymous
0 points
11 years ago

I like wikis more than you do, but I wouldn't recommend mediawiki because of its fundamental antagonism to permission controls. This is a killer deficiency for most enterprise knowledge base implementations.

Confluence changed direction a couple of years ago, hiding the wiki syntax behind the WYSIWYG editor. They clearly decided to focus on the "typical business" user at the expense of their techcomm audience.

?
Anonymous
0 points
11 years ago

Yeah, Mediawiki's open permissions are problematic for a lot of situations. Mediawiki is good if your access and collaboration needs parallels that of Wikipedia, basically. Also, I'm not sure that Mediawiki's transclusion has any better results with search than Confluence. What I do like is the ability to work directly with wiki syntax or HTML. Mediawiki is also pretty robust in terms of its feature set.

Have you ever worked with a wiki that wasn't full of a bunch of outdated, authorship-unknown content?

Tom

?
Anonymous
0 points
11 years ago

Sorry, but I don't agree at all.

The argument about content re-use and comparing Confluence with DITA is like comparing apples and oranges. If you assume to use Confluence both as authoring and publishing platform, please tell me how to do that with DITA? Let your readers read XML files? How would you make sure they read only the content for the relevant audience? It is actually possible to export from Confluence and use a publishing tool chain to produce online help, PDFs, or even books (just one example that has been authored in Confluence: http://www.thelanguageofcon...)

With regards to the rich text editor in Confluence. Agreed, that it has its glitches - as many other WYSIWYG editors do too. But other than highly specialized (XML) authoring tools, Confluence lets tech writers escape their silo, and get to collaborate with the whole organization:

  • developers can provide input in same system the tech writers are working in;
  • service people can ask questions and provide feedback in the same system;
  • tech writers can include co-workers with twitter-like @-mentions and shares to ask for feedback
  • ... I could go on here, but I think the most important benefit of using a multi-purpose collaboration platform like Confluence for tech writers, is that there work becomes visible and more fun.
D
David Carrington Jr.
0 points
8 years ago

No doubt it's a good tool for collaboration: that's what it was designed for. But as a doc creation tool it is simply terrible.

?
Anonymous
0 points
11 years ago

Stefan, thanks for your comment.

DITA does separate authoring from publishing. In some ways this is problematic because it lengthens the publishing cycle. When you want to update a page in your help, you have to regenerate all the help and re-upload it to your server. With wikis, you just edit the page, make the change, and when you save the page, the browser publishes it.

Additionally, DITA's paradigm is to publish different variants of the content as separate deliverables. However, having output 1, 2, and 3 may not make sense for audiences who are not that divided and who want to see content for outputs 1, 2, and 3. Dynamic content filtering, which would allow users to select attributes and have the content dynamically shape around that attribute on the same platform, is something only possible with advanced DITA publishing platforms.

I'm not really sure what you're asking when you say, "If you assume to use Confluence both as authoring and publishing platform, please tell me how to do that with DITA." I'm not suggesting that you do that with DITA. XML doesn't automatically render into HTML in the browser. (There is a guy who created that functionality to some extent, but it's a work in progress.) I'm arguing that this paradigm in Confluence is what gives rise to the complications I described.

Re "It is actually possible to export from Confluence and use a publishing tool chain to produce online help, PDFs, or even books," yes, I am aware of this. The PDF looks pretty good, I have to say. However, PDFs aren't a deliverable I need. The HTML is pretty weak -- it's a single file with jump links. I think Microsoft Word can also publish out to HTML, but that doesn't mean I'd use it to publish a website.

Re books, such as with the Language of Content Strategy, that's an area I don't know much about. It would be neat to learn more about the back-end publishing workflow of how you're mapping Confluence pages to an HTML site page. Even so, it seems kind of like an inflexible model. What if I change around pages and IDs -- I assume that I would have to adjust all the mappings. If you want to write a guest post that describes how The Language of Content Strategy site model works from a technical level, I would welcome it.

As far as the collaborative benefits to wikis as an advantage that outweighs the lack of wiki markup, I admit that in some environments, collaboration on wikis can make tech authoring more fun. But wikis are problematic overall. They lead to redundant, outdated content (ROT). I explained why here.

?
Anonymous
0 points
11 years ago

Thanks for the feedback and thanks for the offer to write a guest post on the making of "The Language of Content Strategy". I'll get back to you about it.

Just on additional note on redundant, outdated content: IMO this is not a problem of a particular technology, it is an organizational problem: If there is no ownership defined for content, and the content is left to who ever wants to edit it, then you will get outdated content. - It doesn't make a difference, if it is a wiki page or a DITA XML file.

Only, it will easier for co-workers to provide feedback and fixes, if the content is a wiki page instead of a DITA XML file.

?
Anonymous
0 points
11 years ago

>But you can’t automate the variant based on login permissions.

Yes and No. If you use Bob Swift's plugins , you can do some fancy variable content based on the individual user.

?
Anonymous
0 points
11 years ago

Good tip, Ellis. Which plugin from Bob Swift are you referring to? I see he has about a dozen of them.