Thoughts on technology and innovation
Ted Husted, Release Engineer
Professional technical writing platforms, like the DITA platform, are an excellent way to create single-source documentation. Hands-down.
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.
I'm not saying Confluence is all unicorns and rainbows, but, for us, it's a step up from Google Docs, and it's head and shoulders above DITA editors.
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
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:
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
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, seeShifting 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.
Ted Husted is a Kaizen Squad developer on the Nimble AMS product crew. "We make the good changes that create a great product."