User’s Manuals

We take a hands-on approach to user documentation. We work with the software so we know it inside and out and have a clear understanding of what the user’s tasks will be and what he or she needs to do to perform them. We not only use the software right, we also use it “wrong”. We try to anticipate the kinds of mistakes users might make so we can alert them to any pitfalls they might encounter. (If one of us screws something up while performing a task with the software, there is a good chance the user will too!)

As a result of our approach, we produce clear, step-by-step instructions for using your software system or product and useful, understandable error-handling procedures. We augment our instructions with screen captures and other illustrations so users have a clear picture of what they are doing on the screen (and we guarantee that you do not have to have 20/20 vision to see them!). Our approach to the content depends on the product and how it will be used in the end-user environment. We know that users don’t like to read manuals. They will read as little as necessary and are more apt to look information up on a need-to-know basis. So we organize and format content logically with informative headings, clearly marked sets of instructions, etc., so they can find what they are looking for—even if they should read the whole thing.

Our approach has one added benefit to our clients. We tend to discover bugs that testers may may have missed because testing is usually structured to test for expected errors and behaviors, while we use the software much as a user would.

Getting Started Guides

Getting started guides give users an overview of the system and the working environment and introduce them to the basic tasks they will be performing with the software. They are especially valuable for complex systems where the user’s manual can be overwhelming to a novice user. Usually, getting started guides are intended for self-instruction. However, If you provide introductory training for your software, they can be used in the training classes as well.

We like to set getting started guides up as tutorials because hands-on experience is the easiest way to learn. Users are often intimidated when confronted with new software and don’t know where to start. The tutorial approach solves this problem. By walking through some simple examples, they learn the basics of your software while actually doing some of the tasks they will be performing on a daily basis, and they've even been known to enjoy it.

For complex applications, creating a getting started guide that is separate from the user’s manual is almost always the best way to go. Including it in what is probably a lengthy manual makes it seem more difficult, while a short separate guide makes it seem doable. If your software is fairly simple and does not merit a separate getting started guide, you can still use the same approach by including a getting started chapter or quick tour in your user’s manual or your help files.

Programmer’s Manuals

Programmer’s manuals are one of our specialties, because we actually can program and understand the way programmers think. We can create manuals containing instructions for using systems, programming or scripting languages, and utilities or tools that are used by programmers to facilitate their work. Whether you need an API guide that shows your customer’s programmers how to integrate a component product into their code, a guide to a CASE tool or coding facilitator, or a guide to incorporating your proprietary DLLs and ActiveX components into your internal programs, we can provide a useful document.

Programmers usually prefer to write code rather than read about it, so our programmer’s manuals are often cast as tutorials. The programmer creates mini application examples where we present the basics they need to know about the tool and some of its most useful (or interesting) optional features. These examples can later be expanded upon or serve as prototypes when they develop their own programs. Often our examples “live on”, adapted and incorporated into the programmers’ applications. Because we apply our hands-on approach to programming as well (regardless of whether we develop the examples or you give us the code—or a combination of both), we really understand the code we are writing about. We also test the examples thoroughly to ensure that they are accurate and actually work.

Programmer documentation is not limited to stand-alone manuals. We have developed user’s manuals for several complex products where either scripting or proprietary 4GL programming was required to manipulate data, provide functionality, or write business rules to tailor the product to the customer environment. For those products, we incorporated the programming instructions into the user’s manual, along with prototype examples and accompanying explanations.

Reference Manuals

Reference manuals are designed for lookup, rather than instruction. They are geared towards people who have a basic knowledge of the software and need information on the function or use of a specific element. They can take many different forms. What is included depends on the type of software. A reference manual for a DLL, for example, would generally include documentation for each of its classes and their properties. methods, and events. A reference for a programming or scripting language would include documentation of its individual elements—statements and functions and their syntax, along with keywords, constants, trappable errors, etc., and, if applicable, objects, properties, methods, and events. A database reference would include information on the database structure and the data types.

Reference manuals can be combined with programmer’s manuals (see previous tab) instead of issuing two separate manuals. This has the advantage of having all the material in one place. However, if the document is too large as a result, two separate manuals may be the better choice.

Reference manuals can be created for internal use as well. Such documentation can prove very valuable when a developer takes over a different product or a new employee needs to get up to speed quickly. What they contain depends on what is being documented and what your company’s developers and associated technical personnel are likely to need to reference. Reference manuals can be created for the software you develop, your internal DLLs that you use in your software applications, other common code in your code repository that is shared by your applications, your database—any software that you reuse or maintain is fair game. The contents of the document can be tailored to your needs.

While reference manuals can be printed, they are often better suited to on-line documentation, simply because they can be quite large, making them too unwieldy to use. In such cases, linked PDF files or a help files (see next tab) can make lookups much easier. It is also easier to keep them current, which can be an issue with internal documentation or products that are frequently revised.

On-Line Help

On-line help can be provided as your primary source of documentation or as a supplemental companion to your manuals. You might, for example, provide a printed getting started guide, then place your main application documentation in your help file. Or your might want your manual to be the main source of information, while help is designed primarily as a lookup reference. Some products provide all the information in on-line help and do not come with manuals at all. One given is that on-line help is expected, not an option. There are very few applications that are sold without it. The help files can be provided with the application and loaded onto the user’s computer or they can be accessed through the application from a central web site. (Needless to say, if an application is web-based, the help will be also.)

Our focus in help files is on accessibility and usability. We design them to allow users to access information in a number of different ways, The table of contents provides a contextual framework. Related topics are arranged in groups and placed in a logical order for the application so that a user who wishes to can use the help file like a manual for learning the application. The index allows users to quickly find specific topics. Browse sequences within a topic group allow the user to browse to all the topics in the group, providing a contextual framework for any topic instead of displaying it as an isolated topic.

When a user opens a topic in a help file, it may be the first topic he or she opens. So it must stand alone. If users need background information or need to know how to perform another task or procedure first, we provide links to those topics, so they can go there if they need to. We also provide links to optional supplementary information or information that may need further clarification, depending on the user level. This information may appear in popup or secondary windows.

Ease of use is paramount. So is reducing annoyances. Users do not like to be accidentally teleported to another topic when they unwittingly click on a link, so most of our links display the linked topic in a secondary window or give users the choice of where they want to display it. Users do not like to scroll through long topics, so we try to break material up into the smallest units possible. When it is not possible, we use devices such as subtopics displayed in separate windows, drop-down text that is displayed on user request, and other techniques to ensure that the topic does not overwhelm. When scrolling is unavoidable, we provide quick scrolling aids and intra-topic links for streamlined navigation.

Installation Guides

If your product has a complex installation procedure where users must install several components (as is often the the case with enterprise-level applications), you will probably need an installation guide. However, simpler installations can often benefit from installation guides as well. “Insert the disk and follow the directions on the screen” does not provide enough information for any application where a user must choose between one of two or more options.

When we create an installation guide, we perform the installation ourselves before we write the instructions and test the instructions after that to make sure that nothing has been left out and the user can follow them. Whenever there is a choice that the user must make, we clearly explain the implication of each of the available options. The presentation format depends on the instructions. For simple applications, the installation guide can be formatted to fit in a CD jewel case. More complex ones may require a larger booklet. For either of these, we can provide printer-ready PDF files with the pages laid out for a folded booklet. You can either submit them to a print shop or print them yourself if you have low volume needs.

If you provide printed manuals, you can place your instructions in the manual instead of creating a separate booklet. They can also be placed on the installation CD—as long as the user doesn’t have to install the software in order to access the instructions!