Documentation, quick and dirty

Under construction, without docs Documentation. I continually say that it’s a necessary evil of any software or hardware project. I’m only half joking about the evil part, and completely serious about the necessary part. In fact, I don’t believe a product or project is ready for release or to go live unless the documentation is complete.

That said, there are smaller firms that can’t afford to bring on a technical writer. There are projects that can’t attract one. But not having documentation isn’t an option. Let’s be honest, very little is so simple that it doesn’t need documentation.

So, what can you do if you don’t have a technical writer or the standard tools? You just might have to go quick and dirty. Quick and dirty documentation is a band aid, no doubt about it. But it’s better than nothing.

Here are some thoughts about ways to deliver documentation quickly and cheaply.

Wikis

Who didn’t see me leading with this? I have to tell you how deeply wikis have become entrenched in the
documentation world. In fact, a lot of firms and many Open Source projects deliver their documentation using wikis alone. Wikis are a great way to publish full user manuals and to get user assistance out to customers.

With a wiki, you can easily separate overview and background information from procedural and how-to information. Because of that, it’s easy to make the help context sensitive linking from an application to a specific wiki page. And there’s no reason why you can’t structure a wiki like an online help system. Make pages on the wiki standalone, self-contained topics and concepts.

Not only are wikis are fast, easy, cheap, to set up they’re also a good way to get your users involved in contributing to the documentation.

WordPress

You probably know WordPress as a blogging platform. But you can also use a WordPress installation to deliver documentation.

WordPress is fairly easy to set up, and all you really need to use one is some space on a Web server and some software –- most (if not all of it) is Open Source.

Posting documentation, like help topics, using WordPress is easy. You can use the built-in editor, or a desktop blogging client. There are even add-ons for some word processors, like the one for OpenOffice.org Writer, that allow you to create the content within a familiar environment and then publish it with a click. Before you do that, you can send the topic around for editing without having to print it or worry that the reviewer doesn’t have access to the blog software.

In case you’re wondering, you can use any blogging platform in this way. I chose WordPress because it’s the one that I’m most familiar with.

Web-based CMS

Like WordPress, a Web-based CMS like Drupal or Joomla! can be quick and dirty way to deliver documentation. Like WordPress, many Web-based CMS are Open Source and can be easy to install or set up. Customizing them is a bit tricky, though.

Google Docs and Evernote

This is where things get really quick and really dirty. Google Docs is a popular online word processor. Evernote is an online note taking app. Well, it’s more than that … But both let you publish files to the Web. If you need a simple and fast way to write and deliver documentation on the Web then these are good choice. Not great choices, mind you. But a decent stop gap measure.

I’ve only seen Google Docs used once to deliver documentation, and I’ll be darned if I can’t find the link. But that’s OK; that particular effort wasn’t all that impressive. And someone uses Evernote to deliver documentation for an Open Source application.

Besides not really being great ways to deliver documentation, your information is in the hands of others. If something goes wrong then your documentation won’t accessible. Or worse.

A PDF or three somewhere

This is probably my least favourite of the quick and dirty options that I’ve been looking at. PDFs are ubiquitious and they’re easy to create. Whether you’re using a commercial tool or an Open Source application, you can usually use it to create a PDF.

To be honest, I find PDFs to be bulky and sometimes balky. They have their uses, but I don’t think they’re a good way to deliver online help. At least not in the long run. As a short-term solution, they work. Just don’t build your documentation strategy around them.

Summing up

Nothing can replace a good technical communicator. A person with the skills and knowledge and experience to write and deliver effective documentation. But until a company or a project can afford to, or find, that technical communicator then quick and dirty documentation will have to be the way to go. It’s not the ideal solution, but in the interim something is definitely better than nothing.

Thoughts? As always, your comments are welcome.

Photo credit: dinostock from Photoxpress

This work, unless otherwise expressly stated, is licensed under a Creative Commons Attribution-NonCommercial-ShareAlike 4.0 International License.

  • Pingback: Tweets that mention   Documentation, quick and dirty by Communications from DMN -- Topsy.com()

  • http://www.sdicorp.com/Resources/Blog/articleType/AuthorView/authorID/24/lkunz.aspx Larry Kunz

    All of this makes perfect sense, Scott. But in actual practice, liability issues crop up — specifically, is your company legally liable when this “quick and dirty” methodology results in the publication of information that’s incorrect to the extent that it causes damage to a customer’s system?

    Are disclaimers practical? Enforceable? Is it reasonable to assume that readers of the information will accept the risks? I’d like to hear your thoughts.

    • Anonymous

      @Larry, thanks for the comment. I don’t suggest that quick and dirty be permanent or considered the be all, end all. Though, as you pointed out in a tweet, that’s a growing trend. I see it as being a stop-gap measure. While something is better than nothing, that something isn’t always great. Or even pretty good.

      I like the idea of a disclaimer. That alone isn’t enough. I think you really need to encourage users to point out flaws in the documentation and help fix them.

      That said, there are areas where quick and dirty won’t fly — specifically regulated industries.

      As I said, quick and dirty should be a stop gap and nothing else. A stop gap between not having a professional TC and having one.

    • Anonymous

      @Larry, thanks for the comment. I don’t suggest that quick and dirty be permanent or considered the be all, end all. Though, as you pointed out in a tweet, that’s a growing trend. I see it as being a stop-gap measure. While something is better than nothing, that something isn’t always great. Or even pretty good.

      I like the idea of a disclaimer. That alone isn’t enough. I think you really need to encourage users to point out flaws in the documentation and help fix them.

      That said, there are areas where quick and dirty won’t fly — specifically regulated industries.

      As I said, quick and dirty should be a stop gap and nothing else. A stop gap between not having a professional TC and having one.

  • Ccardimon

    “Quick and Dirty” is my middle name. Grin.