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.

How to Speed Up a Slow Computer (for non-technical PC users)

Definitions

by Jerry Stern
Computer Tech and Webmaster at PC410.com
  
Most computers run far more slowly than they should. Either they’re infected, or loaded with startupware, or they’re running too much old junk. The key to cleaning these up is knowing what software is running, and managing it. If the computer is infected, the cleanup is a bigger topic, and not always possible for a computer user that isn’t a computer tech. But slow is another matter, and can be dealt with by anyone who is comfortable running an UNinstallation program from Control Panel.
  
Here are the basics of why Windows PCs slow down and what to do about each:
  

  • Hardware: Usually, that’s not as common as it sounds. Most PCs can stay usable into a seventh year of service. Yes, SEVEN years, IF the software that must run is reasonable and not hardware intensive. Ask a local tech if your processor and memory and hard drive are still OK for the programs you run. It is always a good idea to use an online backup service or a back up drive to keep copies of your data.
  • Fragmentation: Make sure you’re defragmenting the C: drive at least four times per year, and after any big software upgrades. I frequently see old XP computers that have important settings files or the mail storage file broken into several hundred pieces–that costs time, and speed suffers.
  • Software Age: Follow my rule of hardware/software matchups: The software you run, other than security products and browsers and browser plugins, should be of a similar age to your hardware. This year’s big office productivity suite won’t run fast on a five-year-old computer, but the same product from the year you bought the computer will be quite usable, and there are faster, smaller programs available for most tasks. Big software means slow, and software ‘suites’ means big, slow, and expensive. So moving backwards a few years to an older version of a big program will generally improve speed; consider the option if you don’t need every hot new feature in the new versions.
  • Security Suites: For security products, suites are more than just slow; they’re evil. They do everything under the sun, and take all the processing power your computer has got to keep them going. Dump every security program that uses ‘suite’ or ‘internet security’ in the name. Switch to a simple antivirus program that doesn’t attempt to interfere with Windows’ built-in firewall, built-in parental controls, or communications in general. Just scanning; that’s all you want. Keeping a computer safe is done by keeping all patches up-to-date, and running a good antivirus program. Suites are not useful; they move spam filtering onto your computer instead of keeping it safely at the professionally-managed server run by the mail service, they tamper with Windows security settings, they interfere with the local network and VPN configuration, and they shut down mail and internet access with no notice. Go small. Avoid security suites.
  • Toolbars: Uninstall every toolbar. These are known by other names–technicians refer to them as ‘browser helper objects’. There was a time when these were useful, and added features that browsers did not have, back around the year 2000, like popup blockers and on-page search features. Those features are built into every modern browser, and browser toolbars are a major slowdown, and having multiple toolbars is a major drain on a PC. This is the most important system change you can make for speed–remove all the toolbars. Use Control Panel, Add/Remove programs to take out all toolbars except anything that’s part of the installed antivirus product, and then turn off the antivirus toolbar by going into Internet Explorer’s View menu, choose Toolbars, and uncheck the remaining toolbar item there.
  • Search programs: Windows 7 has a good built-in search program–it’s the box at the top-right corner of every ‘Computer’ window. Uninstall all others. These especially include Nero’s built-in search program and Microsoft’s Search 4.0 add-in program, but slower machines also don’t do well with Google Desktop, and as of now, Copernic does not run properly in any 64-bit version of Windows. In general, remove every search program that you can’t live without.
       If you find one search program that you really must have, and there’s only one, OK, but be sure to set it to never index the computer during hours you’ll work on it–don’t rely on the defaults, which will set it to build indexes ‘during inactivity’ which means ‘as soon as I start typing, GO’.

Those are the most likely and the largest computer slowdowns on Windows systems. If the hardware remains in good shape, and you keep the installed software simple and small, most modern PCs can last seven years for internet surfing and email. And that’s what I always here from home users. It’s all they run. That, and Freecell, Picassa, and Hoyle Casino….
  
Still slow? It may be time to get expert help from a local computer tech. If you’re near Westminster, Maryland, call me. Elsewhere, take a look at ComputerRepairLocator.com to find a local repair shop.

Virus Warning! (Generic Reply to a Forwarded Hoax)

Definitions

by Jerry Stern
Computer Tech and Webmaster at PC410.com
  

Dear Friend–

I’ve received your latest forwarded message about the virus that is going to destroy the internet as we know it if we open that email with the urgent-sounding title. Please don’t forward these to anyone–they create FUD. That’s Fear, Uncertainty, and Doubt. They do nothing positive.

The message was, to begin with, old. When it was new, it had a few almost-true near-facts in it, like the name of a real email subject line. Everything beyond that was like listening to technology news on my local television news stations–it’s last week’s news, or last year’s news, with the important parts left out.

What you need to remember about forwarded messages that arrive in your mailbox is that they’ve generally been out and about being forwarded, for years. Decades, even–I’ve received forwarded jokes and cartoons that also showed up on my desk by fax in the 1990’s, and by interoffice photocopy-of-a-photocopy in the 1980’s. Forwarded emails are old, old, old.

And security news is meaningless after five days. All good antivirus software blocks every known threat that’s more than three days old. The bad guys know this, and they change their approaches to getting your system infected constantly, sometimes twice a day on some of the big families of rogue malware. Now, while there are bad emails going around that will infect your computer if you haven’t patched it, or that contain evil infectious links, the bad guys change the subject lines daily to keep their messages from being caught by SPAM filters, so trying to block them by not opening an email with a specific subject line isn’t remotely practical or safe.

So by forwarding this old message, you’re scaring people, and encouraging them to get their security news by watching for it to fall into their mailboxes from the sky. There are valid sources of security news, and forwarded email isn’t on the list.

Several points to keep in mind–every one of these tells you this is either a hoax or badly-reported ancient history:

  • Microsoft and Norton don’t need your help to report news. For that matter, neither do CNN, Neiman Marcus, or Homeland Security.
  • The message is undated.
  • It asks you to forward the message.
  • It claims knowledge from a credible source, but it’s a generic source that can’t be reached, like ‘Microsoft’ or ‘NBC’.

The best thing to do with these forwarded messages is to delete them. Don’t spread the FUD.

The REAL Microsoft security news is here:
http://technet.microsoft.com/en-us/security/default.aspx

The REAL security news from the US Department of Homeland Security is here:
http://www.us-cert.gov

And here’s an article by Rob Rosenberger on ‘False Authority Syndrome’, to help you recognize hoax emails:
http://vmyths.com/fas/