Thoughts on technology and innovation
Ted Husted, Release Engineer
How you can implement a custom help site for your Salesforce org, like the one at help.nimbleams.com (in three parts).
Warning: There's a lot you can do to extend Salesforce help, but we need to create a few prerequisites along the way. Part 1 of this blog steps through the org setup. Part 2 walks through the setup for an external online help site (you are here). For extra credit, part 3 (you are here) covers creating and maintaining a help site using the DITA XML format.
Salesforce is unopinionated as to what you yourself use to create your own help site. In part 1 and part 2, we looked at configuring Salesforce and configuring your own web server -- but what do you put on your own web server?
And -- this is important -- how do you coordinate rolling out new help content with rolling out a new version of your application?
Three options leap to mind:
DITA - The Static Site Generator for Professional Technical Writers
Unsurprisingly, firms like IBM have long felt the pain of managing technical documentation for software and hardware products. Not one to stand idly by, in 2001, IBM introduced Darwin Information Typing Architecture, or DITA.
DITA is a “single-source” XML format that can be used to publish deliverables in any number of formats, including Webhelp, PDF, XHTML, Rich Format Text (Word), and ODT (Open Document Format), and really just about anything else. There are a good number of professional XML editors for DITA, including XMLMind XML Editor, oXygen, Codex, and EasyDITA (a cloud-based offering). Under the hood, a DITA XML document bears a strong resemblance to XHMTL. Anyone who has edited HTML by hand can do the same with DITA.
Why Flat File Rocks!
Essentially, a dynamic CMS stores content in a database and transforms it on the fly. Flat-file systems and static site generators store content in markup files and transforms it on demand.
If you are already building an application using source code, like, say, Force.com metadata, dollars to donuts, you already have a "flat-file" content management system up and running. The content may be source code files, but it’s content none the less.
In truth, Markdown and DITA files are source code, plain and simple. We transform Java or C# to binary resources, and we transform DITA to XHTML or PDF deliverables. The process is identical, and a flat-file CMS can easily use the integration infrastructure you already use to to deploy a help site.
Whatever you already do with Apex source code, you can do with DITA XML source code. You can branch it, test it, review it, and merge it -- just like source code: because it is source code.
DITA in a Nutshell
The best practices in technical writing are to
Pro Tip: Always write the tasks first, then only the concept topics needed to support the tasks, and finally reference topics for grisly but helpful detail, like a table explaining error messages.
Topics are added to ditamaps to create a table of contents. A deliverable is created by passing a ditamap to a transformation utility that converts the DITA XML to a target format.
Since DITA separates semantics from presentation, it’s easy to use the same source to create both Webhelp and PDFs. It’s also easy to reuse the same topic in multiple ditamaps, or multiple times in the same ditamap. (Ditamaps are glorious!)
Here’s my DITA task topic for writing help topics:
Continual Integration with DITA
In development, we often use integration servers to compile software, and the same system can be used to transform DITA. We develop Nimble AMS using short-lived task branches, and we do the same for DITA topics. A topic is born on its own branch. A technical writer crafts the topic locally. When the branch is committed back to BitBucket, TeamCity deploys the updated content to a Web server subsite, for peer testing and code review.
Leading up to a seasonal release, we conduct customer previews in sandbox environments and we also standup a preview copy of the help site. With DITA, "Bob’s your uncle!"
One DITA speed-bump is the lack of high-quality templates for rendering webhelp sites. The Open DITA Toolkit project provides an adequate template, and editors like oXygen and XXE provide better templates, but you need to watch the licensing terms. For example, the very nice oXygen webhelp template requires a separate and pricey license for use with a continuous integration system. Happily, XML Mind distributes an open-source DITA transformer (DITAC) that works well with continuous integration servers. Since DITA XML is a true OASIS standard, DITAC works with any compliant DITA XML documents, regardless of what editor you use.
Here’s the DITAC one-liner that builds our entire help site.
There are other ways to pass parameters, but I like to keep it all in one place. The %env.TARGET%attribute resolves to the local path.
We run a TeamCity Build Agent on the web server and build test sites directly to folders under the web root. When we are ready to go live, we use good ol’ rsync to copy the approved site up to the web root
Of course, rsync works between servers too. I know folks who render a static copy of Confluence on an internal server and then use rsync to copy it over to a production server every few hours. Works like a charm!
How to be a Wordsmith
If any part of your job includes documenting software, I strongly recommend “Developing Quality Technical Information: A Handbook for Writers and Editors”. It’s not DITA specific and it’s a must-read for anyone authoring technical documentation.
Hope that Helps!
What formats have you tried for technical documentation? What’s working for you? What are your biggest pain points now?
Ted Husted is a Kaizen Squad developer on the Nimble AMS product crew. "We make the good changes that create a great product."