Category Archives: Definitions

What’s startupware?(tm)
The source for all definitions of startupware.

How to Write Instructions

Written by Jerry Stern
Chief Technical Officer at Science Translations

In the brave new world of always-online software, help files have changed. We used to write HLP files. Now, it’s compiled hypertext, or CHM files, or sometimes, it’s a web page, and not much else. Format shouldn’t affect function, but it does–the industry is getting horribly sloppy, and have forgotten that help files are about teaching, and are not about searching.
What has to be in Help?

A help file, regardless of the format, needs some basic structure. Certain questions have to be answered; they’re the same questions that applied in writing class. When writing Exposition, or writing that explains, or Reporting, writing about events, include as many of these as possible: Who, What, When, Where, Why, and How. Mostly, help files won’t include a lot of ‘why’, but try for all of them. When writing a help document, start with this outline, and expect to change the headings when it’s almost finished:

• What does the software do? Include a short description of what the software does. This isn’t a sales pitch–it’s an introduction to the software, what the workflow of the program is like, and what kind of projects are possible in the software.

• How do I get started? Include the simplest possible project, how to start creating a task, how to learn about the program, and how to save, export, publish, or display the finished task–not all of these apply to every program–choose the simplest case, and explain it.

• Where are the commands and functionality? Tell the user where you’ve hidden all that wonderful functionality, in toolbars, in the menus, in keyboard shortcuts.

• When do I use these menu choices? Include the basic sequence of steps in an introductory project.

• Why do I choose to do things this way? This is why your software matches the workflow for a specific task, best to follow a specific sequence, or it can be a description of several sequences of tasks that will work, using your software product.

• Who published it, and who are they? Include contact information, links to additional help, tutorials, and updates.

First things First

When writing step-by-step instructions, sequence is your top priority. Here’s a horrible example:

You can change the settings for communications. Check off “use alternate port” in options.

What’s wrong with that? Well, it’s vague–it doesn’t say why or when you would use these instructions. It’s out of sequence–the steps are not in the order that they become visible to a user; first list where to go, then what to do. Not what to do first and then where to go–that encourages reading backwards while the user skips forward for navigation, and back again for the option to click. Finally, it looks like the option doesn’t match the software menus, and it’s not totally clear what the menu names are labeled.

Try again:

When the software won’t connect to the remote server, an alternate port may be used. Go to the Tools menu, choose Options, and at “Use Alternate Port”, add a checkmark in the option box. Click OK to close the dialog.

What changed? First, there’s a short explanation of ‘what’ at the beginning–in real software documentation, it should be more specific. Second, the steps are strictly in the same order as a user would see them on-screen, and no steps are left out. Third, the name of the option is precisely the same as in the menu, including capitalization and underlined menu shortcut keys.

Advanced Topics

Here’s a far more complex example, taken from a WordPerfect Magazine article I wrote, way back in 1992, about creating greeting cards in WordPerfect:

Begin at the WordPerfect document screen. Press Format (Shift F8),
(2) Page, (7) Paper Size/Type, (2) Add, and (9) Other. Type ‘Card’ and press(Enter), then (8) Labels, (Y) Yes.
A new menu will appear for the label definition.

The format for magazine writing of this kind is extremely precise. Every menu label appears, with the shortcut key, and every keystroke is included, with enough information at the end to let the reader see that they’ve arrived at the right place.
This level of precision can add confusion when the program is translated. The number selections work in every language, but the letter options may not be consistent. Be careful when translating sequences of menu choices, or plan ahead during menu design to keep steps and shortcuts consistent in all languages.
Should you use this type of magazine style for help topics? On some topics, yes. Think of a short article, maybe a few paragraphs, for an extended example of how to do a task or create a project in your software. It’s a great introductory lesson, but include every step, and choose a very basic first project for the example.

Describe what Menu Options Do

I frequently wonder what a menu entry does in a program I’m trying out. I look for the matching entry in the help file. For example, under File, Export Stuff, I’ll find this:

Exports stuff in a file.

Wrong, on so many levels. First, it tells me nothing that isn’t already in the name of the menu entry. Second, it doesn’t tell me what or when or any of the other basic answers. Try again:

File, Export Stuff: Saves the current project in a special format that provides __fill-in benefit here__. The Stuff format is used for ___. This function is also known in other programs as ‘Save As’, ‘Publish To’, or ‘Send to a Service Company’.

Huh? What’s all that stuff in the last line for? Well, that fixes the next problem, of searching a help file for a function you know exists in a program, when you don’t know the name. It’s the elementary school complaint about dictionaries and spelling–“how can I look up the spelling if I can’t spell it?”

Well, when you search help for what you think an option or function is called, and don’t find it because the author has been very consistent in always calling an export an export, what happens? Not a whole lot, beyond thinking nasty thoughts. Telepathy doesn’t help; keywords do. Those alternate names are there for searching the help file by keyword.

In the Deep End without a Paddle

Many programs now have only hypertext help with search, and no table of contents. It’s very Wiki, and worthless for learning a new program. In these monsters, you can press F1 for help, and if anything happens at all, there’s a pop-up of search titles related to a topic. It should be a topic related to the screen that was displayed when F1 was pressed. That’s ideal, and that was the standard form of help, 10 years ago.

But now, too many programs display nothing but pages and pages of unfiltered word matches for every attempt to search. Make sure that the novice-level information doesn’t get buried; the users that need advanced help know how to search, and are already sold on using your program. Novice users don’t know your program, may not have bought it yet, and are easily discouraged. Keep it simple for them–quick help searches should lead to intro-level topics, and then to advanced, and not just dive into the greatest possible depths of trouble-shooting chit-chat.

No matter what the format of the help documents, include a table of contents or a good index, include an introductory lesson, and remember that help isn’t a list of dialog box names–it’s a directory of how to use your software product.

Jerry Stern runs Startupware.com, and is online at www.PC410.com.

WinDefender 2008 in the Wild

A recent rogue cleanup was easier than usual–there was an image backup to restore, and there was time to backup the contents of the infected drive before cleanup, and scan it a few weeks later with the newest, latest greatest antivirus/antispyware definitions. All the “infections” shown below are fake, of course. And WinDefender 2008 is a rogue (fake) security application.

At scan time, here’s what was found (Scan by AVG antivirus 8.0):
Virus:
C:\Program Files\WinDefender 2008\Uninstall.exe
Classified as ‘Trojan horse SHeur.BZLW’

Adware:
C:\Downloads\SetupGamevance.exe
Classified as ‘Potentially harmful program Downloader.QN’
(2 copies found)

I see no proof that Gamevance is pushing WinDefender 2008. Or not. But here’s the scenario: The machine passed all scans the day before the rogue appeared. So either they showed up on the same day, arrived in each other’s company, or were both hidden by active malware. Assuming simultaneous infections is a big assumption. Caution is indicated with any site paid for by installing software, as usual.

Trialware and the Dell Vostro

Dell has had its share of bad press over bad decisions. Usually, they’re like most big companies that just don’t get it. Now, they’re advertising a new series of computers, called “Vostro”. No, I don’t know how they could possibly trademark that in Italy, where it would mean “Your Computer”. Like I’ve said, bad decisions. Could have been worse, like sending the Chevy Nova to Spanish-speaking countries, where it means “doesn’t run.”

But maybe they’re done something right. Never know. Random roll of the dice, and all that. The Vostro will, according to the press release from July 10th, be somewhat free of what they’re calling Trialware.

New York, July 10, 2007

Dell today extended its commitment to customers with a new brand of notebook and desktop computers designed for small businesses. The VostroTM branded products feature no trialware and simple to use tools that address top-of-mind problems such as data back-up, PC performance and health, and specialized networking support for customers without dedicated IT staff.

The Vostro (Latin for “yours”) product and services family is a milestone in the company’s strategy to reduce the cost, time and complexity of managing information technology for customers of all sizes.

OK, now this sounds good. Then again, they don’t really understand what their customers want:

Regardless of geography, small businesses told Dell that tools to help accomplish common, time-consuming tasks associated with backing up data and optimizing system performance, and easy support options rank among their top IT needs. To address these needs, Vostro customers receive automated support tools customized for small business at no additional cost for the first year (minimal charges may apply in some countries).

The tools include Dell Automated PC Tune-Up, which reduces more than 30 tuning, performance, security and maintenance tasks to one click; Dell Network Assistant, which simplifies the set-up, monitoring, troubleshooting and repair of a customers’ network; and Dell DataSafe Online for online backup of up to 10GB of user data and protects against data loss resulting from disasters, theft or damage.

Translation: Dell isn’t going to include Trialware, which is the word they’re using to describe free trial software that they get paid for any time a PC user clicks through and buys, upgrades, or views ads from the icons and pre-installed software on all their other machines. Instead, they’ll provide up to one-year versions of their own private-label clutter that changes standard Windows functionality to favor their own system, and auto-runs at startup. Prices for these “solutions” after the first year’s free trial weren’t announced.

Good? Well, maybe. Depends on implementation. If the startupware they install is designed to work together, it’s a smaller burden on the system than the usual combination of startupware, trialware, and bloat. But calling these boxes ‘clean’ would still be false–they’re still loading products beyond Windows and hardware drivers.

Have you bought a Vostro? Post a comment back and report if the configuration is an improvement.

More information: Here is Dell’s press release.