Manage changes in documentation

Question

Hi there,

I would like to migrate my documentation to Confluence. Wether it has something to manage changes in the requirements? I would like to have some sort of widget/tool/macro which would track changes and make substitution in relevant places automatically. Let me give the example. Imagine you create documentation of a bike. You've got 40 pages, in which you mention a helm 15 times. At some time, you decide to rename "helm" to "rudder". It would be super cool if something said hey, you've got 15 places, where you had "helm", do you want to change them all to "rudder" now?

Robert Reiner _smartics_ · Answer

If I understand your problem correctly, your requirement boils down to the Single Sourcing problem. If you would define the elements of your domain (e.g. helm) each on a single page (e.g. in a glossary) and use links to this single page, then every time you change the title of the page in the glossary (e.g. fro helm to rudder), the links in your text would automatically change.

This approach has some drawbacks:

* You would have a link on each mentioning of the term 'helm' which is probably very confusing for the reader
* If the term is not in its native form (e.g. helms - plural - instead of helm) the replacement won't take place

So I assume this would not work in most real world settings.

Rachel mentioned the projectdoc Toolbox (where I am one of the authors). There you would have access to the Display Document Property Macro (and its cousins) to render a property defined on another page. For instance you could have a glossary item for helm (where you describe the helm) and there is a Name property 'helm'. If you would use this macro whenever you mention the helm in the body of a page, the rendered string would change automatically when you changed the Name property from helm to rudder.

Again, their are drawbacks that probably make this approach too cumbersome in the real word:

* Adding the macro (instead of typing the word) is very cumbersome
* The string helm is probably not part of the Lucene index, since the value is dynamically generated by a macro

The only advantage to the link approach is that you could control whether or not the string helm is a link or not.

If your use case would be that the terms are only rendered in lists or tables, the projectdoc Toolbox provides macros to do so (see for instance Display Table Macro or Transclude Documents Macro (multi-excerpt / transclusion)). But I suppose your use cases are not that easy.

Unfortunately I also do not know a tool that would automatically do the changes you require. A simple text replacement on pages may work, but could be obviously dangerous. There may be match where should not (Mr. Helm would be Mr. Rudder) or you have a grammar case you have overseen (Helms would still be Helms instead of Rudders).

Роман Ковалевски · Answer

thanks a lot, Rachel, I'll look into this ones!

R. Fuerst · Answer

Hi there,

Currently there is not a built-in way to achieve this in Confluence, though I could see how this feature would be super useful! I went ahead and created a Feature Request with our product team:

* CONFSERVER-56085

That said, there are a few add-ons that might help you with certain aspects of what you’re looking for:

* priojectdoc Toolbox for Confluence
* Live Input Macros

I have not used the add-ons above, so I cannot guarantee their performance or features, but based on my research they seem to enhance Confluence for documentation purposes.

I hope this helps!

Rachel