I’ve been thinking about documentation tools and publishing platforms. I’m evaluating what I have, and what more I need. To be less vague: I have an online knowledge base/help center. What I need, or might need, is a way to provide that content to users who aren’t online.
After setting up and writing content for wikis and other online-only systems for years, the concept of “offline documentation” seems obsolete, even primitive. But I have to admit that there are still some use cases for it, even if the letters P, D, and F make me shudder in fear.
Ok, that might be overstating it a little.
Offline docs = stone tablets
Once you move the documentation offline, it’s as good as set in stone. Any mistakes and incomplete information are locked in forever, and those docs will never know about new features or workarounds. After having written manuals for years, I was more than happy to focus on online documentation and leave that messy publication workflow behind.
Because it was messy, and we (the writers) knew that it forced the documentation to be less than it could be. When our docs had to be translated, we had to finish the documentation well before the product was complete. As I remember, we would shut down the docs sometime around code freeze. Which has always been an idealistic goal and milestone. We knew full well that features would be slipped in after code freeze, but we were already giving the translators the absolute minimum amount of time needed to translate those manuals into ten, twenty, or more languages.
So everything that happened after code freeze, including new features and lots of fixes, were dumped into the release notes. Which made for bloated release notes that were required to navigate the documentation: A user would need to cross-check the manuals with the release notes to discover the truth about the product.
Moving from books to topics
The other big change was to stop writing books, and start writing topics that could stand on their own. It took some time to get away from the conceit that users would read topics in TOC order, and would therefore would only encounter topic C after reading everything in topics A and B. It’s obvious to me now how misguided this was, but we were basing the online help on the manuals, and the easiest thing to do was to pour the manuals into a conversion utility and then slap the output onto the product. You could then check the box that said “Provide online help,” without thinking about how helpful that really was for the users.
But after using help systems, myself, I quickly realized how stupid that solution was. Even when I would start to read online help from the first topic, I would eventually start skipping around, following links to new topics, losing the order, and by losing the order, I would lose context. I’d get into a subtopic and have to navigate to its parent to figure out what was going on.
So: Easy for the tech writer rarely means easy for the reader. Your reader doesn’t care about the painstaking research and the elaborate publishing process you went through to get them that information; they just want their questions answered! And they also don’t need to read a history of your product, and about its multitude of wondrous features. They’re looking for information about one workflow, or details about one feature.
Mark Baker has written a thousand blog posts and an entire book about this. Clearly, there’s a lot of frustration about this issue.
But back to the main point
So: Online is great because the publishing workflow is faster, lighter, and more efficient. At least, it should be. Translation is still going to take time (unless you’re really willing to trust Google translate, and want to amuse or confuse the heck out of your non-English-speaking users). I have the luxury of publishing to a single language, which means that the speed at which I can write or update a topic is determined entirely by how fast I can write. Once the content is written and reviewed, and I’ve added some tags and keywords to improve SEO, publishing just means clicking Save. And then all of my users can access the new, improved topic and everyone is happy.
Unless they want to read it offline. Then we have problems.
Offline docs: PDF?
One option would be to write in an authoring tool or use a workflow that allowed me to output to both online (HTML, XML, XHTML) and offline (PDF, and…er…?). I don’t have that set up yet, because it hasn’t been a priority. But it was at my last job, and for that I installed a PDF conversion feature onto the system, and I created a topic explaining how to do that (and a video, too). The main, and possibly only, customers for this were employees who were traveling and wanted to read some of the docs while on an airplane. They needed to save multiple topics to PDF, and the tool (fortunately) allowed for that. It was never great about saving all of the topics to PDF, and you’d just end up with a giant mass of topics, anyway, but that was never a use case that I needed to address.
I have no idea whether any users created PDFs from the docs. It wasn’t something that the program tracked, and no external users ever asked about it.
PDF at least allows for links, so users (once they’re back online) can navigate to other help topics for more info. But saving to PDF from the online knowledge center (or any help system) never produces something as nice as documentation designed specifically for print. But most users aren’t as concerned with this as we (content creators) are. Again: They’re looking for an answer to a question, and aren’t worried about the font used for the footers or the exact placement of page numbers.
Which is not to say that we shouldn’t worry about those things. I know that’s an impossible request, anyway (I really did spent time trying to get those footers to look better, I swear!). But users are willing to accept some limitations, especially when those limitations really aren’t limitations to them and don’t affect how they consume the information.
An example of providing offline docs
Here’s my experience: Some people on the professional services team asked for docs that they could read offline. I tested the PDF extension, made sure that it was working correctly, and did what I could to improve the output. This involved mucking with the print CSS, and fighting with that and the limitations of the tool until I got something that I considered acceptable. Or at least at the limits of my ability to improve.
Then I created a tutorial, showed it to the professional services team, and they said, “Thanks! Just what we wanted!” And that was it. No one complained about the look and feel or about how the company logo should have been a little larger and maybe centered instead of on the left and what was up with those page numbers…
They didn’t care. They knew that those docs were good as of the minute that they saved them to PDF, and were possibly inaccurate after that point, so they were essentially disposable once they’d read them.
What is my argument, anyway?
I’m honestly not sure. Let me review, for my own benefit:
- Online docs are (usually) easier to publish, and low publishing requirements result in more accurate documentation.
- But some users still need offline documentation, so we need to provide that.
- Offline documentation should be considered obsolete 5 seconds after it’s created.
I don’t know of a way to set an expiration date on PDF files, but adding an auto-generated “created on” date is a good idea. Admittedly, this is both useful to the reader and a bit of CYA for us.
Even though everyone has a laptop and tablet and cellphone that can access and view your knowledge base (because your knowledge base looks good on mobile, right?), we should account for those times when people are offline, or have their internet access restricted by their place of work.
And I have to admit that supporting offline access to the documentation is one of my next tasks. In most cases, users need to be online to use my company’s product, so I can assume that they can access the online doc site, too.
Unfortunately, there are some cases where that’s not true, and we will need to support on-site installations. Those users will be stuck with static, quickly obsolete documentation, and I’ll need to work with engineering and professional services to come up with a good solution. We’ll have to update those installations every so often, so it would make sense to give them updated documentation at the same time.
Fortunately, customers with those requirements often receive a lot of training and follow-up care, which reduces the need for documentation (although it also increases the costs for everyone involved).
Conclusion, sort of
So that’s another item for the 2014 To Do list: figure out how to deliver doc updates to those customers, and a way to create those docs isn’t prohibitively difficult (or just annoying) for a one-person doc team to set up and use.
And I haven’t even thought about how to deal with the videos in the documentation…