Style guides  Clip to Evernote

When it comes to style guides, I’m of two minds. I know that they’re useful, and provide a framework for creating consistent documentation. On the other hand, I’ve seen far too many writers and editors become blinkered by the style guide — it’s an all-or-nothing proposition.

During my time at The Company That Shall Not Be Named, a technical editor went ballistic on me because I put Canada before United States when describing the choices from a geographic location list. The style guide, a sacrosanct tome, stated that United States always comes first. It didn’t matter that I was describing how the list looked in the GUI.

When I said that the company’s style guide was a tome, I meant it. The book was several hundred pages long. A bit too big and bulky in my opinion. I’ve never encountered an in-house guide quite that large, but some have come close. And others have been pretty brief.

Aside from some of the well-known style guides, I’ve encountered very few that were any good. That said, here are some of the more interesting and useful style guides that I’ve run into recently:

Do you have a favourite style guide? Tell us about it by leaving a comment.

Reusing content on a wiki  Clip to Evernote

In a previous post, I discussed moving a large piece of documentation from Word to a wiki. That got me thinking about how to reuse content on the wiki — there is some potential for reuse in the documentation. It turns out that TWiki (the wiki that’s used here) enables you to do just that.

How? With the %INCLUDE{...}% variable. This variable mimics text insets in FrameMaker. You have the content that you want to reuse in a topic on the wiki, and then place the %INCLUDE{..}% variable in the topic in which you want the content to appear.

You’re not limited to content on your wiki, either. You can point to files on a server or Web pages. And you can make the include as granular as you want — down to the section, paragraph, phrase, or even word level. Although I don’t see the point in the latter …

Last weekend, I was reading Sarah Maddox’s blog, and she mentioned how this is done in Confluence — a solution that’s a lot more elegant than the similar feature in the other wikis that I’ve used. In Confluence, you can have an inclusions library. Sarah explains this in more detail in her post.

Overall, What’s your experience with reusing content on a wiki? Feel free to leave a comment.

Is printed documentation dead?  Clip to Evernote

I don’t know about you, but in recent years most of the documentation that I’ve written has been distributed electronically — as PDFs, online help systems, HTML, and even on a wiki or two. The last time I held a printed and bound guide that I’d written in my hands was a couple of years ago. And, to be honest, it was a strange feeling. In a good way, though.

From what I’ve seen, and the technical communicators with whom I’ve chatted, it seems like printed documentation is dead. If not dead, then dying. Which is a good thing in many ways — especially when you consider the resources used to print and bind a manual or set of manuals.

But there are situations in which a printed manual is a necessity. I was reminded of that when I talked with Teresa Mulvihill-Talbot at DocTrain West in May. During our conversation, Teresa mentioned technicians in the field repairing printers. Obviously, in that type of situation, hard copy documentation is a must.

Why not electronic docs? People in the field might not have wired or wireless network access, so getting to a central repository of information will be impossible. Sure, the could have the documents on a laptop or a PDA but there might not be enough space for these devices in a work area. On top of that, there are the ever-present dangers of the battery running dry and not being able to plug in, and losing or breaking the device.

Printed manuals can be lost and damaged, too. But it’s cheaper to replace them than an expensive piece of electronics. And let’s be honest: not everyone is comfortable reading on a screen.

Thoughts? Feel free to leave a comment.

Creating documentation for the small screen  Clip to Evernote

It’s amazing how quickly small mobile devices have become commonplace. It wasn’t that long ago that a PDA was viewed with curiosity and the smartphone was a rarely-seen small brick called the Nokia Communicator. How times change …

One of the challenges that some technical communicators are facing is how to create effective documentation that will fit on the small screen. While I’ve written documentation for a few mobile applications, I’ve never prepared docs specifically for viewing on a mobile device. Which is one reason I’m looking forward to Tamara Knezic’s presentation at DocTrain East in October.

In the meantime, three questions for any takers:

  • Have you been creating content for mobile devices? If so, which device(s), using what tools and in what formats?
  • What changes (if any) did you make to your authoring and writing styles?
  • Do you know any good online resources (besides Forum Nokia and the W3C), aimed at technical communicators, that cover creating content for mobile devices?

Feel free to leave a comment on any or all of the questions.

Businesses not as keen on blogs and wikis? We had a hunch  Clip to Evernote

This article at Network World mentions two new reports out from Gartner and Forrester citing the low adoption (thus far) of blogs and wikis in the enterprise. According to the article, 64% of companies surveyed had no plans to implement web 2.0 tools including blogs, wikis, and RSS feeds. So what’s going on here? Despite all the excitement in the technical communications community over these technologies, it looks like companies are still reluctant to tie the knot for a variety of excuses reasons.

This shouldn’t be a surprise to technical communicators. The user manual paradigm is still alive and well in a lot of tech comm departments. Management is often reluctant to try out web 2.0 technologies because of security concerns, lack of knowledge, and control issues.

As technical communicators, we need to create meaningful analogies and examples of how these technologies can deliver information to end users more efficiently, effectively, and with more relevancy than the status quo. We all need to become evangelists of these technologies in order to spur a greater adoption. Take what you’re doing now and ask yourself. Could this content be more usable if delivered on a wiki? Are we incorporating enough information from our user base? Do we even have a mechanism for including the wisdom of our users?

The term “web 2.0″ is now as tired and meaningless as “dotcom”. Corporations have heard about it for years but still believe these technologies better suited to organizing photos and posting about famous celebrities than improving communication. We need to change that.

From a tech comm perspective, have your employers or clients been receptive of these new technologies or are you still bound by the paradigms of a user manual? We’d love to hear your stories.