Documentation: From Programs to Products

microISV How-To's

by Jerry Stern
PC Tech at PC410.com

OK, great program. Now, what’s next?

There are some basic differences between a program and a product. Most software developers understand many of these instinctually. As a program becomes a product, on-screen messages are made more specific. Screen layouts are more polished. Errors are trapped and result in plain-text messages that help resolve problems, or even-better, are user-proofed so that incorrect procedures still create great results.

But that’s mostly programming code and artwork. The biggest difference between programs and products is the documentation. Specifically:

  • Sales pages and advertising.
  • The user manuals.
  • The instruction books.
  • Help files.
  • Screen shots, slide shows, and videos.

If these are missing or are incomplete, the product won’t sell like it could, or at all.

There are several basic and common errors in documentation for modern software that aren’t quite product-ready:

  • Not writing documentation. (You know who you are…)
  • Or combining the various types of documentation, and skipping over a basic need. There are five types of documentation. A real product must have all five types, and while they can have minimal overlap, all basic types should exist for nearly any software product.

Five Types of Writing

Before writing any of the documents below, stop and choose a writing style that will work through that entire
task. Changing style isn’t about formality or slang–it’s about the basic reason for writing. The basic writing styles are:

  • Exposition: Writing to inform, to explain a process or an event or an object. Your main help file should be mostly expository writing.
  • Persuasion: Writing to persuade. Frequently includes classical rhetorical techniques to bring the reader to your point of view. Applies to press releases and other sales-related documentation. Classical rhetoric is the most difficult writing style; use it with caution and a light touch.
  • Descriptive: Writing to describe and define what a product looks like and how it behaves.
  • Narrative: This writing is common in fiction, for telling about a sequence of events, but it can also apply to a wizard-style product interface.
  • Creative: Novels, plays, poetry, stories. I’ve seen these used well in product documentation, but only once in a utility program. Needed in many games, but avoid them in most other products.

The majority of your product documentation should be exposition or descriptive writing, and your sales documents should be persuasion with a little rhetoric. Overlap them more than just a little, and your document will lose focus and effectiveness.

Five Types of Documents

Here too, try not to overlap the types of documents below.Breaking these into separate projects makes them easier to write, easier to understand, and more effective. (Or, for the software types among us: Less likely to result in a tech-support contact.)

Motivation

These are sales documents, your web site, press releases, your advertisements, promotional emails, logos, artwork. These include the sales pitch, the classic AIDA steps of Attention, Interest, Desire, and Action. In short:

  • Attention: Something not routine. Something that stands out. Unique. Maybe bizarre, if your product isn’t a
    business application. Anything to get potential purchasers to look.
  • Interest: These are the product descriptions, written as benefits, not a feature list. It’s about what the user can create, and not about the tools and instructions.
  • Desire: Why they want it. Or will. This is where the “Ooooh-Ahhhh” goes. The excitement should be building.
  • Action: Call for action, go for the closing, ask for the sale. Buy now!

There’s a reason that sales letters from the very largest product sales companies are four pages long–they’ve tested the letters, included every step for attention, interest, desire, and action, and they know it works. But that format is best on paper or television. Adapting a non-sequential web or software version will take more work. A video or demonstration may be a better approach to building the AIDA steps.

Instruction

Getting-Started Guides: These are the most-left-out documents in modern software, and the most likely to prevent a technical support call. These describe basic screen layout, functions, what always must be done first, and what the words on the screen mean in the context of just this product. Instructions are meant to be read by new users, not word-searched, and must be organized in a logical progression:

  • What does the product do?
  • What can my final project or result be?
  • How do I get started?
  • What’s the basic navigation through the program?
  • What’s in every use of the program, or what steps are in every project?
  • And finally: A description of where the rest of the help is, in the tutorials, demonstrations, and references.

This documentation should always be included in the product installation. It can be duplicated online for sales and Search Optimization purposes, but it’s so basic to using the product that it should always be included in the product in some form.

Tutorials

This is how to work through a series of introductory steps and learn the basic operations of a product. Tutorials are for new users. These may be slideshow format, or help files, or videos. These will frequently include building a project of some complexity, by starting small and working though many continuous steps to add options to the project. These are typically numbered, and build on each other to bring the user to a level of mastery, step-by-step.

There’s a trick to tutorials: keep every step strictly in the sequence that the user will take them on-screen. It’s “Go to the File menu and click on Print” and never “Click Print in the File menu.”

Tutorials can be included directly in the product, or online. Frequently, the best approach is to include basic tutorials on program layout and project steps within the help file or a ‘Getting Started’ popup, and include a link to bigger and newer tutorials online.

Demonstrations

These are step-by-step guides, frequently done as animated slideshows, for a single and specific product task. Demonstrations are for users already familiar with the basic operation of the product. These show how to do processes or projects, and leave out no steps. These can be used as needed, in isolation, and should not build on other demonstrations.

Demonstrations, like tutorials, can be within the program, or online, or split, with the advanced topics online. But tutorials are sequential and introductory, while demonstrations are standalone and project-based.

Reference

This is what programmers want. It’s the notes for the advanced features, the guide to doing complex items, and the ever-growing tips and tricks list. This works well in a Wiki format, or a searchable knowledge base. It’s not the material that most users of the product would memorize, or must know to use the most basic functions of the product.

Knowledge bases and Frequently-Asked-Question lists are mostly online. Basic FAQ topics should move into the
Instruction guide during revisions to the product. Advanced topics should usually remain in the knowledge base.

Hiring a Professional Writer

Can documentation be outsourced? Some can, but not all. If the programmers have started the reference documentation, and created a basic tutorial that a writer can follow (in any form, including a one-on-one lesson), then a writer can convert that tutorial into a form ready for a general audience, and start building the tutorials and possibly some of the basic demonstrations.

More mistakes:

Using marketing documentation as an instruction book. Selling is not teaching.

Using a feature list as a press release. Features don’t sell, and bullet lists don’t read well. Selling requires sentences that promote benefits. If your press release is made of lists, it’s not a news story, and won’t be published by any media companies.

Interviewing yourself for press releases or product sales. No, wait–are you Steve Jobs? This rule may not apply, then. Everyone else–don’t quote yourself in your press releases or on your web site.

Mixing tutorials with demonstrations: A guided tour is not a step-by-step procedure; combinations will become
large and overly complex. Again, tutorials are sequential, and demonstrations are for single tasks.

Using an online Knowledge Base or a Wiki as a help manual. These are for problem solving, and can’t replace an introductory set of lessons, which should include a tour, terminology, and getting started with some basic projects.

Consistency

Finally, use the same terminology everywhere. A folder is a folder, and not a directory. A picture is a picture, not an image. Both may be correct, but pick only one, and then stick with it.

It’s great to have a glossary that includes mentions of “This is also known as …”; that helps the search function of your help (or Google, for online help) to find entries when users look for help on topics that you don’t have listed in the menus or the help contents. But overall, be consistent-–this is more about clear communication, and normal writing rules that say not to overuse single words do not apply here.

Keep parallel sections of the documentation similar. Maybe they should all start with a definition, or a screen shot, or an image of a finished project. Pick one style, and stay with it.

Finally, read it all out loud. Well, everything except the reference materials, anyway. You’ll hear errors in your writing far more easily than if you see the words on-screen. And you’ll notice that sections of your text belong somewhere else, and that leads to better organization and betterproduct documentation.

Jerry Stern is the editor of ASPects, the ASP’s Coordinator of Anti-Spyware Operations, runs Startupware.com and WorPerfect.org, and www.sciencetranslations.com.