Though, in real life, the editing software is not mere-mortal friendly. If you’re a full-time help topic author, learning DITA editing software is well worth the effort. If you write documentation in between other things, jumping into a DITA editor can be a real struggle.
Being Atlasssian folks, we’ve started to use Confluence for our enterprise wiki, and it’s quickly become our new standard. Google Docs has its benefits, but the platform is still raw in many ways, and lacks much of the maturity and “finish” we find in Confluence.
As we migrated more-and-more internal content to Confluence, using Confluence for our Nimble AMS help topics became a natural progression. The major stumbling block being: How do you version a Confluence space?
If you (google/bing/yahoo) around, you’ll find a lot of tips and tricks for using plugins, permissions, smoke, mirrors, and elbow grease to version Confluence, but our use case seems more straight-forward.
Like Salesforce, we go through a preview/production rollout every four months: We preview our new release in customer staging environments for a time, and then roll out the new release to all of the production environments. (The Release is dead, long live the Release!)
To manage our product help pipeline, we need to
- synchronize production help content with production code changes,
- roll out a preview help site as part of our major release rollout, and
- port the preview content to the live site once the new major release is in production.
As much as I adore continuous delivery, our use case begs for a conventional code/test/live pipeline, where we can start with a Dev version of the space, roll that over to a Preview version, and then put the Preview version into Production. Bada-bing, bada-boom.
Problem is, Confluence doesn’t directly support the notion of merging or synchronizing spaces or changing the space URL.
Indirect support … well, that’s a fresh kettle of fish.
The indirect bits are:
- Exporting a Space and changing its Key.
- Dropping a Space and importing another in its place.
The workflow bits are:
The content originates in the Dev space. When we’re ready for a Preview version of the updated software, and a corresponding preview version of Help, we just
- export the Dev space,
- update the export XML to reference the Preview space Key,
- delete the Preview space (to free up the Key), and
- import Dev as the new Preview space.
The same process then holds for Preview to Production.
Since the new content uses the same URLs as the old content (because we imported under the old space Key), our page rank is preserved, and people are not confused by multiple sites.
Updating the key in the XML export is a bit groddy, but it’s far from the worse thing I have to do on any given day.
For the semi-official step-by-step, see
Shifting Keys is much simplified if you use a Key that is not going to appear as part of another string. With a Key like “HELPDEV”, you can make the switch to “HELPPREV”, or to “HELP”, in a single find/replace pass.
If we need to correct any production or preview content, as in a typo or misinformation, there is a bit of rework, in that we update dev and then update production, but that’s simpler than trying to hide this-or-that until it ready for the big reveal.
So, if you are a cloud shop, like us, and roll out continually, don’t be distracted by shiny objects. Sometimes the old ways are still the best ways.
