Moving from internal Confluence to 'publishing' for customers

[David Sidwell]

Hi all. Just joined up today, but have been lurking for a while. The place I'm contracting to uses Confluence for internal information exchange (plus Jira for issus etc). My role is Tech Writer. We are now looking at moving away from Word/PDF for customer docs and onto Confluence (self hosted)

Is there a guide on things we should be looking at? We aready have it working with AD and would love to have an approval workflow. We are also wondering about tying in these documents with the version of the actual codebase, so a customer on Release 61 of our s/w can quickly see the Confluence items appropriate to 6.1 (maybe using labels and some sort of filter?)

Anyway, early days...but we are making good progress so far.

Thank you

[Martin Kellner · Accepted solution]

We are looking at Confluence for technical documentation too at the moment.

On one hand you lose some features for formating pages. Do we really need all these features for technical documentation? I don't think so. More documentation and up-to-date documentation has a greater roi I think. Customers would be more lucky. ;-)

On the other hand we hope to get better results when you have more than one author for each document. I collect several items from different colleagues. Some of them have to be converted to e.g. Framemaker as the final authoring tool. Switching to Confluence might give us the ability to eliminate these steps. I also don't have version control if I use pure Framemaker. Colleagues could comment the documents in a much better and faster way.

At the moment I'm missing only a few things in Confluence:

- conditional text (as in Framemaker). you can help yourself with the multiexcerpt plugin. But this is only a workaround.

- Interface to external translators: At the moment I can exchange Framemaker documents with the external translators. With confluence I have to change this workflow. I don't have an idea at the moment what could help here. The best would be a plug-in that only grabs the updated pages. This would decrease the translation costs by a great amount.

[David Sidwell]

Yep, we've just hit the issue with the auto-numbering of lists 'resetting' after an image etc. Not good as we have lots of numbered steps with screen shots in the middle. We may revert to Word-saved-as-PDF for these docs, then attach them to Confluence. As they can be Labelled, they appear in our 'content by Label" lists. Not ideal, by any means. But at least the PDF content per se is indexed.

[SarahA]

Hallo David

Do you mean the numbered lists reset within a Confluence page, when viewing the page in Confluence? (As opposed to PDF exports or something other than Confluence.) If that's the problem, then you can get round it by using Shift+Enter to create a line break (instead of Enter alone).

In other words, press Shift+Enter, then copy/paste the image (or macro, or other block-level item). The auto-numbering is not triggered by Shift+Enter.

The auto-numbering will continue next time you press Enter.

Cheers, Sarah

[David Sidwell]

G'day Sarah. Thanks for that, it was a Word (.doc) format import. It had lots of (step) 1, 2 , image, 3, image, 4,5 .... and lots of the step numbering got reset back to 1. I've done some searching and can't find any equivalent work arounds. If you know of any, pls sing out!

[Matthew J. Horn]

This is such a rich and varied topic, I wish there were a mailing list for technical writers who use Confluence where we could share workflows/ideas/etc. I've been managing my company's Confluence install for a little over a year since it went live, and it's challenging but a helluva lot of fun. More fun than Frame, that's for sure. :)

[SarahA]

Hallo David

Depending on your requirements, Confluence can be a useful tool for user-facing documentation. I'll answer your questions one by one. :)

Is there a guide on things we should be looking at?

This guide explains the overall flow: https://confluence.atlassian.com/display/DOC/Developing+Technical+Documentation+on+Confluence+Wiki

We... would love to have an approval workflow.

Take a look at the Ad Hoc Workflows add-on: https://marketplace.atlassian.com/plugins/com.comalatech.workflow

We are also wondering about tying in these documents with the version of the actual codebase, so a customer on Release 61 of our s/w can quickly see the Confluence items appropriate to 6.1

We use spaces for version control. For example, the docs for version 6.0 go into one space (maybe with a space key of DOC060) and the docs for version 6.1 go into another space (for example, DOC061). Here's a blog post that explains how we direct the online help links from the product to the relevant version of the docs: http://blogs.atlassian.com/2007/12/using_a_wiki_fo/

I hope this helps!

Cheers

Sarah

[David Sidwell]

Thank you all very much for your quick and interesting replies. I'll digest them and see how we go. We've been carefully labelling the articles and found the Content By Label macro quite useful, particularly the logical "AND" operation. So our articles have labels like "R61" [release] and "Tips" [doc type] - and it's easy to create the list of Tips documents just for Release 6.1

The lack of 'official' Approval Workflow is a bit of a worry. We will check out the 3^rd party one but we may have to look towards another approach for approving and ‘publishing’ documents to our public web site.

[DavidH]

Depending on the complexity of your documents (number of illustrations, flows and columns, indexes and xrefs) and your distribution requirements (print, digital, web, etc.), there are a number of hurdles.

Coming from a background of FrameMaker, compiled online help, and print documentation, I find Confluence to be a real compromise. The lack of custom formatting beyond the H1, H2, p and list tags really limits layout complexity (it's difficult to do sidebars, wrapped illustrations, multi-column llayouts, and other formatting I take for granted for a real book).

The export to PDF for printing is a pain, and there are a number of refinements and fixes still needed to produce documents that have basic print documentation niceties, like running headers/footers, indexes, and easily customized TOCs. The PDF output also produces bad word and page breaks without custom CSS tweaking. You'll want to know a lot about CSS to customize the PDF export. Plug-ins may solve a lot of these issues, but we are running without any commercial plug-ins.

I know a lot of people are gaga over Confluence for documentation, but I find it a step backward from the features of a dedicated tool like FrameMaker (or Dreamweaver, Expressions, RoboHelp, etc.). Still, it has the advantages of being easy to use, accessible from anywhere, provides simple versioning, and overall it's easy to use for reviews/commenting. If you are not ever going to print out books, a lot of what I find lacking will not be an issue.

Hope that helps a little.

[Anna McDonald]

Hi there. Did you ever succeed with using Confluence to publish technical documentation?

[Deleted user]

Confluence is fantastic for writing user documentation. You can use tags (sorry, 'labels') on pages in conjunction with content-by-label tables to create self-updating lists that show customers exactly which pages relate to specific releases. You do have to be disciplined about applying the labels.

Just one little thing to beware of - Are you going to let the users view Confluence directly, or will you export pages to PDF? Because I believe there are lots of outstanding issues with PDF export in Confluence 4 & presumably 5.

[David Sidwell]

It seems most of the users will be online (so can see our website) but 1 or 2 may not, so PDF 's may be needed. Thank you!

[Matthew J. Horn]

FWIW, a thread came up recently on the same topic as this one, so I went and created a mailing list for technical writers that use Confluence:

http://groups.yahoo.com/group/confluence_tw

Feel free to join, or not. :)