startupware.com

by Jerry Stern
Editor, ASPects

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 is the editor of ASPects, the ASP’s Coordinator of Anti-SpywareOperations, runs Startupware.com and WordPerfect.org, and is online at www.PC410.com.

The Federal Trade Commission has gone to U.S. District Court, and shut down, at least for the moment, Innovative Marketing, Inc. and ByteHosting Internet Services, LLC, who they’ve identified as the source of such nasty-ware as WinFixer, WinAntivirus, DriveCleaner, ErrorSafe, and XP Antivirus.

Here’s their press item:
http://www.softwarekb.com/news/2008/12/11/court-halts-bogus-computer-scans/

This group of rogue programs has made this past year interesting for me. I clean up these programs more than any other type of malware, and yes, I get paid. But all in all, I’d rather be upgrading hard drives and building new systems.

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.

Sun Microsystems sent their CEO, and he’s clearly the best CEO speaker I’ve heard at a long series of these events. He speaks, teaches, amuses, and of course, sells pretty much continuously, and keeps to a schedule. Scott McNealy is clearly in touch with the real world. And he has made the transition to open source, completely and emphatically. He’s giving away Sun’s intellectual property, online, in-person, everywhere. Just before FOSE, he returned from a trip to China, where he told the Chinese government that he would provide, free, Solaris and Java software, and development help, and the Ultrasparc high-end processor plans, so that China could build their own hardware systems and provide automation services to their economy. He has made a similar proposal to Germany and some other countries–not all countries are ready for such a proposal, he says, with skills, but not enough technology already in place. Free.

His talk was all about Open Source; it would have worked just as well at a developer’s event as at government talk. His main point: Sun makes money giving away all their intellectual property, and then selling services and contracts. There are five public reasons he pushes open source. A sixth, unmentioned, is surely that expanding markets for open source expands markets for Sun Microsystems–they’re clearly a large enough player to benefit from that type of marketing.

1. There is no barrier to entry for users of open source products. Selling a prototype project to a corporate purchasing department shouldn’t start with requests for funding for software, just to see if what’s needed is possible. Just download it, and get started.

2. Increased interoperability. The source is out there, so there are no proprietary formats; every competitor is free to copy how you’ve done processes, and link into them, or add functionality.

3. More Research & Development. A closed source development project might have 5 programmers, or 30, working on it, he says. In open source, testing and bug fixing is open to a world of interested parties. It’s all extra help for the R&D staff.

4. More Secure. For the same reasons, open source is tested and hacked by the world before being declared as ‘done.’ There are no hidden secrets, it’s all out there to see, before deployment.

5. No barrier to Exit. There are no service-level agreements forcing years of product upgrades to future versions, site-unseen, and no site licenses in open source; there are no contracts to tie down a corporation or a government to continue using a product that’s last year’s bad news.

Sun is making money, lots of it. McNealy’ opening joke was that he stopped by Washington DC to pickup his $600 tax rebate check, and to deposit a few million $ for his 2007 tax bill. Open Source is clearly working for Sun–they claim to be the world’s largest provider of it, and they’re profitable even after spending huge amounts to defend themselves and their clients against software patent claims. They don’t start law suites over intellectual property, but they do defend, vigorously, and half their winnings go back to an open source legal defense fund.

Sun competes on the basis of providing service to clients. Their model sounds closer to that of a service company than to a software publisher. Scaling their model down to the level of a microISP is clearly challenging; some software developers are already working on the basis of custom installations and ‘whatever-you-need for a fee’ service. More will clearly have to work that way in the future.

McNealy closed by giving away a large stack of software CDs to every attendee, but remember that this is to a US Government audience that can’t accept gifts valued above $20. “It’s worth $8 for all the plastic. The content is available for free at developers.sun.com. I’m just saving you download time.” He doesn’t stop selling. Ever.

Google sent the Vice President in charge of their Google Enterprise division for the first keynote address and slide show of the FOSE conference at the DC Convention Center. According to David Girouard, the future is in the clouds. Well, cloud computing. Yes, this speech was given on April Fool’s Day, also known as the 4th anniversary of the launch of GMail, but what he was promoting was the migration of documents onto the ‘cloud’ (storage on the Internet) and positioning Google as a SAAS vendor.

Those of you who attended the Shareware Industry Conference during the years it was in Florida around ten years ago will remember that SAAS, or Software as a Service, was really big back then, but it resulted in very little. Now, bandwidth and connectivity for business users is good enough and fast enough that SAAS may be practical for specific applications.

Putting documents into the cloud is already what Google is living on. All their documents, spreadsheets, slide shows, etc, are hosted live on the Google Apps site (www.google.com/a). Nothing is stored on workstations, and their technology now includes sharing of documents between collaborators, with tracking of edits and changes.

Girouard reports that lots of business notebooks are lost worldwide, usually with business data. He had one stolen from a parked car the day before a big meeting. The next morning, he stopped by the Google IT department, picked up a new notebook, switching to a Mac while he as there, logged in to Apps, and was up and running immediately, with less than half an hour lost.

This isn’t just Google eating their own brand of dog food. Girouard showed an impressive list of Fortune 500 companies that are using Google’s GMail with Postini spam filtering for 100% of their email storage. It’s all online, manageable and controllable by corporate management.