Online vs. offline documentation

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:

  1. Online docs are (usually) easier to publish, and low publishing requirements result in more accurate documentation.
  2. But some users still need offline documentation, so we need to provide that.
  3. 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…

Advertisements

10 thoughts on “Online vs. offline documentation

  1. The problem you describe about offline docs not being written in a topic style is something I’ve seen frequently, and is usually a result of untrained tech writers producing the manuals. The writers that I have worked with who have qualifications in tech comm have always written manuals in topic form too. Each section of the manual works as stand-alone. That’s because the vast majority of readers use paper manuals in the same way as they use help – they dip in and out for the info they need; they don’t read it in any order. This approach has been around for at least 20 years, because it was 18 years ago when I was taught it!

    Hard copy manuals are sometimes required for reasons other than technology not being available too. In some industries there are legal requirements to have a manual on site, and there are environments where electronic devices should not be used.

    Readers only want the answer to one workflow? Sorry, I disagree.The majority of users want to use help for this reason, but there are times when a user wants to ‘browse’ the help to see what the product can do. I’ve seen it many times with complex programmes, have seen help used in demos for the same purpose, and have even done it myself – especially with photo and drawing programmes, where I don’t know what every feature of the product can do. Are people going to search for ‘features’ or ‘overview’ or do they want to browse the features, like they do on retail web sites?

    For your customers with on site manuals, couldn’t you email them an update reminder prompting them to download the latest PDF (or other format) and print it for use on site?

  2. Thanks for the comment, Craig!

    Part of the problem (for me) was that I learned tech writing from writers who were used to creating manuals, and still assumed a narrative-style flow. I had to unlearn a lot of that when I really started writing online help. It became obvious that people used printed or PDF manuals like you say (dipping in and out), or even not using them at all (because who really bothers with a 1400 page PDF, unless they have absolutely no other choices?).

    I don’t work in an industry that requires hard-copy documentation. A friend of mine who documents financial software has to deal with that, and I’ve heard his stories of late nights spent tweaking Framemaker scripts to produce both PDFs and online help…and I’m glad that I’ve been able to focus on online-only. But that means that I’ve convinced myself that hardcopy docs are horrible, primitive things that people really don’t want or use (see the previous paragraph). I’d much rather spend time implementing in-product docs, and get away from the product/documentation split as much as possible. But I haven’t solved that, either.

    Workflow: You’re right, of course. I was thinking of the user who has a question and wants an answer *now*, not about the user who is browsing for information about your product. Again, it’s due to my situation: My docs are behind a login screen, and only users can see them. Those users have been through the sales process, and training, so they should have a pretty good understanding of the product.

    BUT…I’m working on something, based on Tom Johnson’s idea of “narrative workflows,” which describes an end-to-end workflow, hitting most of the functionality of the product (there will be one for each of the industry verticals that we’re targeting). And because the docs are behind that wall, I’m working with our sales team to create pre-sales content that’s more technical than marketing content, but not quite as technical as the documentation (more like the feature lists that you describe).

    As you can see, I can be unreasonably biased against doc types that I’m not working on at this very moment. I blame the startup culture. 😉

    Email reminders: That’s probably the best solution. That’s something that the to-be-created customer success team can really help with, too.

    1. Yes, I think that it boils down to a lack of ‘tech comm’ education. I’ve seen people who are ex-programmers, ex-engineers, or just good at English so were hired as tech writers make that sort of mistake. I’ve just spent the evening writing a blog on creating stand-alone topics for manuals as well as help, with a small example of a structure that I’ve used in a few different industries, both online and offline, without any problems (so far). My site is being revamped right now, so as soon as it is up and running , I will post it.

      1. Depends on the topic, though. Getting Started manuals are linear of necessity. But with SaaS, that process is shorter, or even non-existent (maybe some configuration steps). Even admin guides were designed as an unfolding process, moving from simple to more complex tasks, even though chapters (or sections within chapters) could often stand alone.

        But we’ve seen online help systems that don’t work well because they’re just manuals converted to online help, often with simplistic rules like “Convert all H1s to separate topics.” Those could be considered tightly-linked help systems.

        Wikipedia, on the other hand, is a standalone system: No topic requires another topic, and most are unrelated (although there are often a lot of links to other topics, so maybe this example is breaking down; and I’m sure someone could prove a strong relationship between carbon nanotubes, Kaiser Wilhelm, and twerking). I think that good help systems (online help/knowledge bases/help centers) are loosely-linked: Each topic (mostly) stands alone, but link to other topics to show relationships and workflows, and work together to provide a full understanding of a larger whole (your product).

      2. I agree. But for the ‘getting started’, I say it isn’t really a manual; it is a tutorial. There is a clear start, middle and end and it wouldn’t really be used as a ‘dip in and out’ type of document. Having said that, I have written tutorials in the past where they consisted of distinct modules. Each module was stand-alone so that they could be mixed in different combinations, depending on what version of the product the customer had bought. So even with tutorials, it is possible to write them as stand-alone topics, but there’s generally less need to do so.

        I think the argument about ditching the TOC for help only applies to wiki-type content, where it is true the end user only searches for a specific term. But this isn’t the case for all help systems, and it could be argued that it isn’t always the case for wikis either…look at Atlassian’s own help for Confluence.

      3. Maybe a getting started guide should be thought of as one long procedure, consisting of smaller sub-tasks. But we’re probably splitting hairs over all of this.

        As for TOCs in help, that’s worth an entire blog post. The short version is that I love them as a writer, but after talking to users I learned that they don’t use them, and often don’t notice that they exist! I spent weeks creating a doc structure, and later found that most users ignored it and went straight to search.

      4. But that’s to be expected,right? Most people will search. The TOC is really there for a minority of people, but it is still useful and has a place (in my opinion). Whether it is worth the time and effort is another issue. But if it can be made automatically, I say keep them (or a menu equivalent).

      5. But the TOC might also be distracting (I’ve received that feedback). Because the TOC is a relic of printed documentation, I think it’s worth asking whether it needs to exist in online documentation. My current doc site is a knowledge base with topic groups, but no overall TOC. And I don’t think that creating one would add any value.

      6. Can the users see all of the topic groups all of the time? If so, that is a TOC (of sorts…it serves the same purpose). I agree that traditional TOCs can look awful and be distracting, but we just need a way of providing the navigational benefits of a TOC without the ugliness and awkwardness.

      7. Users can see the topic groups, and a few topics in each group, and that’s the intention: If they are looking at the documentation for a product (which is how the knowledge base is organized), they can see those main areas and find their way. Assuming that the section titles provide enough context, of course.

        The problem comes with nested TOCs, and I think that was the main problem that I created: A nested structure makes sense for the writer, but it’s too difficult to navigate for the reader. Too many clicks (which can be “greater than 1”), and having to follow a path down through topics and sub-topics. Anything more complex than a single-level TOC is very likely going to be ignored.

        This is based on interviews with internal and external customers for a couple of companies; I’d love to see some more data about this.

Comments are closed.