Evaluating Confluence for technical documentation

[Martin Kellner]

If I look at the product description of Confluence one area of usage is "technical documentation". I have a local installation of confluence running on my machine. I'm missing two features:

- conditional text: Ok there is the "multiexcerpt plug-in", which could help at this point, but it isn't an easys way to go. I'm coming from adobe framemaker and was also looking at the DITA-standard. On both platforms I can combine single chapters or topics to or by a book or map. I don't think, that there is a feature like this in Confluence. I can only reuse pages with the different excerpt-plugins. Is there another way?

- Workflow with external translators: How would you setup this? I installed the "language plugin". But this doesn't help me to get a workflow to external translators. I would need a function to get all changed pages in the basic language. Then transfer these pages to the translators and import them again in the right context after translation. Any ideas?

[Stefan Kleineikenscheidt _K15t_ · Accepted solution]

Doing tech docs on a wiki is more bleeding-edge than I expected when I started looking into it.

Amen. But be assured that we at K15t Software are dedicated to make wiki-based tech docs work well for all tech writers. :-)

Our next steps (in Scroll Versions 2, to be released in the first half of April):

• support for product variants incl. conditional text both on page-level and content-level (block/inline).
• page maps (aka DITA topic maps)
• dashbaord for better management of the documentation
• ...and a lot more.

So that should help for conditional text.

With regards to translation, external translators and translation memory we have built customer specific solutions based on XML-export/-import. Please contact me at stefan@k15t<deletethis>.com if you are interested in details.

Stefan Kleineikenscheidt,
K15t Software

[Robert Lauriston]

Doing tech docs on a wiki is more bleeding-edge than I expected when I started looking into it.

I think Confluence's excerpt plugins let you do the same things as conditional text in FrameMaker even though the workflow is very different.

Scroll Versions promises some of the capabilities that DITA + a content management system provide:

http://www.k15t.com/software/scroll-versions/overview

Confluence's source is XHTML-based, so should work with translation memory. Some possibly useful info:

https://answers.atlassian.com/questions/72208/organizing-and-displaying-content-in-multiple-languages

[Martin Kellner]

The "excerpt concept" differs from the "conditional text concept" as you already wrote. You might lose track of your document. I Framemaker you can give each condition an own color. So write your text, the decide that it belongs to a certain condition and the color always helps you to keep track.

If you use the excerpt concept you have to write these different variants of the text in different pages and then put them togehter in another page.

E.g. we have a software that exists in two different versions. In one version we have 2 ways of some kind of a workflow in the other version we have 3 different workflows. So I could write "you have 23 different workflows". Of course This doesn't mean 23 different workflows ;-) The 2 belongs to one condition, the 3 to the second condition.

If I describe these workflows in the following paragraphs I can always see one paragraph in the first color and another paragraph in the secon color. Ok, you could break it in two different pages in confluence, but you must handle the whole document in this way. I think ee have more than 50 paragraphs in a document that are differ for the two versions.

In Framemaker I switch the conditions in one chapter, copy/import them to all other chapters and then I can create the PDF file for this versions.

Concerning the translation workflow I have different ideas. Some need more work in confluence or a special plug-in, others just copy the old workflow. The intelligence still is at the translation agencies as in the past using their translation memory technology. But this approch still doesn't save costs as it could be done with an intelligent export.

[Robert Lauriston]

There's no counterpart of FrameMaker's conditional text UI in Confluence, but what would the Confluence equivalent of that feature be?

When you share a page among multiple Confluence spaces, you want a FrameMaker-like conditional text widget that displays different content depending on which space the page is being viewed in?

In a Confluence environment, I'm not sure it makes sense to conditionalize at the page level. A more Confluence-like approach to that might be to have a library of snippets / variables / text insets that could themselves be shared across spaces.