Implementing usability without UI standards

Have you ever tried to implement some basic usability principles in an application that was developed without a set of UI standards or guidelines? It’s almost an impossible task.

As a technical communicator, this situation presents a great opportunity to hash out some basic UI guidelines to enforce consistency and a standardized look and feel across the application. Sounds great, but does it really happen as often as it should?

From my experience, attempting to come up with even the most rudimentary set of guidelines for UI design as a writer is an uphill battle. It’s that one task that the development team certainly doesn’t want to get involved in, yet in no way do they want a technical writer creating guidelines about how they are going to code their application. What to do?

Some strategies that I’ve used in the past (to varying degress of effectiveness) include:

  • Adapting industry standard guidelines
  • Creating a quickPowerPoint or Camtasia demo to show a better workflow
  • Involving as many stakeholders as possible in the UI design process*
  • Insisting that UI design become a critical component of the development lifecycle

* One strategy to avoid is developing a set of standards on your own. It’s vitally important that you involve as many stakeholders as possible so that you can build a consensus over a period of releases.

Have you been frustrated by the lack of UI standards on a project? What was your strategy?

Style guides

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

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?

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

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.