Documentation Planning Tools and Strategies FAQs

Q: How can I assess my project’s scope?

A: Whether you are working on a new software release or an upgrade, a procedural document or a technical resource, it is important to be accurate in determining the kind and amount of documentation that is most appropriate for your project. The documentation should offer the intended audience the information they need to easily and creatively use the product or follow the recommended steps to use a piece of equipment or medical procedure. Specification documents and other existing documentation for both new and revised software should provide a detailed description of the product’s intended use and capabilities, and therefore a starting point for assessing the needs of the project. This documentation, along with marketing materials describing the target audience, offer the basic information you need to decide how to approach scoping the project.

To scope a documentation project:

Determine the audience. What is their level of competency with the product? How do they learn most effectively?

Outline the major uses of the software package, procedure, or equipment.

Review the developer’s specifications to determine how many graphics are needed to document the product. For instance, if software, how many screens must be captured? If hardware, how many diagrams and schematics of its exterior and interior features are needed? If a medical process, are photographs more effective than line drawings? How many steps are included in the procedure?

Develop a flow chart of the procedures that your users will need to use your product or process properly.

Determine the deliverable dates. For instance, when will the developers be ready to release a stable beta version of the software? When will a prototype of the hardware product be ready for examination? When is the product going to be in stores? When is the software due for release? How many procedures need to be documented, and by when?

The next step is to meet with the experienced project management staff available to you from Underwhelmed. We can help you determine the best approach for communicating the essential information your target audience requires to make the most efficient use of the product your company is working so hard to develop. Underwhelmed refers to acknowledged industry standards to determine the requirements in detail. This provides you with an accurate snapshot of the ideal production process, and allows you flexibility to adjust your budget by increments, knowing that the numbers will track no matter which way you revise the scope—up or down.

For more information, please see the Underwhelmed white paper "Our Process: Offsite and Fixed-Cost Documentation Projects".

Q: How can I determine a realistic budget for my project?

A: Industry standards are a great help in beginning to work with your budget. The best-case scenario is one in which documentation is a valued part of the process of bringing your product to the market, and the budget is adequate for the needs of your staff to accomplish its task. In the real world, however, money is typically doled out sparingly to the publications group to create its work product. In addition, scant time is allocated to most software documentation teams, and they do a lot of their work very late in the process, but often must finish the writing before the software is completed by the developers. Documenting procedures, medical processes, or hardware equipment all have their own time constraints, depending upon the development process, the availability of subject-matter experts, the level of confidentiality required for proprietary intellectual property, and the readiness of the product or process to be documented.

The safest approach is to focus your resources so that the documentation meets the needs of the greatest number of people in the most concise manner. The seasoned professionals at Underwhelmed can work with you to develop an overall approach and detailed information plan that meets this goal within your budget.

For more information, please see the Underwhelmed white paper "How Your Investment in Documentation Improves Your Bottom Line".

Q: How much time should I allow in my schedule for my project?

A: The amount of time you need for your project is determined by a number of factors that are never the same for any two products. However, one rule in very broad use in the technical documentation field is that new documentation written "from scratch" should take approximately 8 hours per page to create, and updates of existing documentation should take approximately 4 to 6 hours per page. These figures include all tasks that are part of the documentation process: information design, information gathering, authoring, graphic design, template development, technical illustration, desktop publishing, editorial reviews, revisions, and project management.

Q: Should I hire a new staff member or get a contractor?

A: When you present us with a publication project or staffing need, a representative from our team of project managers can help you determine what is needed to fulfill your requirements. Here are some of the questions we ask you:

Are you developing a software product with upgrades in mind, or do you require just one documentation set for a proprietary application? Is the equipment you are bringing to market an uncommon type requiring highly specific skills and background, or can any competent hardware documentation specialist do the job?

Is the major effort concentrated on writing, or are the revisions simple enough to require only the services of an editor?

Can your company afford to hire another full-time staff member?

Will there be an adequate amount of additional work the new staff member can perform after the initial project is completed?

Does your budget allow only a quick learning curve by the writer, or is a longer-term investment in an experienced individual trained properly in your techniques, system, and software more cost-effective?

For more information, please see the Underwhelmed white paper "Staff and Contract Personnel Search Strategies".

Q: Should I use an onsite contractor or an offsite team?

A: Here are some issues to consider:

What are the available resources at your office? Do you have any empty cubicles, unused computer systems, and excess software licenses available for use by onsite contractors? Do you have an onsite manager or team that can supervise the work of an onsite specialist?

Is the company planning a move within the next 6 months due to lack of space? Are there currently more people than computers at your office? Are you starting to seat two people in a cubicle?

Does it take more than 2 weeks to get a computer workstation set up for a new staff person?

If you are working in this kind of environment right now, it is probably advisable to consider hiring an offsite team to develop the documentation. The costs are actually lower if you take into account the use of resources and overhead to orient the new people, and to set up cubicles, desks, offices, computers, and other tools and necessities of a workstation.

If you choose to hire an offsite team, pick someone on your staff to become the designated contact person. We recommend an easy-to-reach person who has the authority to:

Process and distribute writer and procedural queries.

Negotiate the complications and intricacies of your company’s rules, regulations, and requirements.

Solve problems when roadblocks appear, as they inevitably do when you are developing a complicated project such as a documentation suite.

For more information, please see the Underwhelmed white paper "Our Process: Offsite and Fixed-Cost Documentation Projects".

If, on the other hand, the job is relatively small and logistics are handled smoothly at your site, then it might be cost-effective to find a place for the contractors to work at your office. Onsite work has the positive effect of creating close relationships between team members, ensuring easier supervision, facilitating quicker and more reliable communication about changes in the plan, and providing more control over the operating system, formatting, and other assorted issues that must be considered in desktop publishing.

The amount of time a contractor using a modem spends downloading the latest beta release from your FTP site can be considerable, when an onsite terminal could make the software available in minutes. In addition, resolving desktop-publishing issues like proper fonts and software compatibility can consume valuable time for both the contractor and your staff representative. If everything the writer needs is set up and available at your office, so much the better.

For more information, please see the Underwhelmed white paper entitled "Staff and Contract Personnel Search Strategies".

Q: Why do I need print documentation?

A: The nature of the project’s audience indicates whether or not the information should be published in printed form. Here are some issues to consider:

What if some of the target audience for information on how to use a piece of equipment does not have access to a computer?

What if the user does not process information on the screen very well, and understands written instructions in print better? Studies investigating the use of help systems show that when users are provided with only online documentation, they print it instead of read it on the screen. A computer screen has the same scan interval as a television screen, and the attention span and absorption levels for online information are therefore far lower than for print media.

What if there is a federally mandated requirement for documentation of procedures to be posted in 3-ring binders?

What if the online help reference system is not detailed enough to help the user solve the problem at hand?

These are all good reasons to think about providing your customer with printed documentation. Here’s another reason that’s not logical, but it is verifiable. Studies have shown that users have expectations when they buy software. They don’t just want a CD-ROM in a box; they want something substantial in the form of a glossy package with a book. Perception of value is essential in marketing a product. Like it or not, until the next generation of users grows comfortable with the idea of getting the entire product on a disk in a jewel case, printed guides will continue to be the traditional vehicle for communicating the value of the software.

We recommend the following approach to use this continuing preference to your advantage: Since longer conceptual topics should be read in book form (at least, that’s the best solution developed in the 600 years of publishing technology), provide the clearest overview, introductory explanations in hard copy form. If this is a software documentation project, have references in the printed guide to keywords that link to appropriate procedures in the help system. This way the user can guide themselves through their learning process while becoming comfortable with the software.

Also, it’s easier and more cost effective to update a help system’s procedure topics that change frequently as opposed to conceptual text in the printed guide that changes less often. Your printed guide will also be shorter and thus less expensive to print and distribute. If the documentation is for use with a piece of equipment or in a medical setting, provide clear graphical representations wherever possible.

For more information, please see the Underwhelmed white paper "How Your Investment in Documentation Improves Your Product’s Bottom Line".

Q: What makes a usable help system?

A: Various types of topics are essential to creating a thorough and useful help system. As help authors, we’ve learned how to chunk information into specific types of topics:

Conceptual/overview/introductory

Procedural/task/how to

Reference

Context-sensitive/field-level

Our clients often ask for only procedural topics to save money, or procedural and overview topics only. But really, all topic types complement one another; so the most usable help system contains some of each, providing the customer/user with complete information.

For example, a user is interacting with the software and wants to enter information into a field, but isn’t sure it’s the right field. Context-sensitive help can make all the difference because a user can easily access a pop-up description of the field. If a user is not sure which screen to use or is having trouble working in a screen, the conceptual overview topics explain the big picture and relate like procedures to one another. Reference topics provide specific explanations, terminology, or listings of shortcut keys, menu commands, toolbar buttons, and error messages.

We have found that the most useful approach is to invest time in the beginning to provide complete coverage for the software. It saves time, energy, and money because your technical support department won’t have to answer so many questions, and your reviews will stimulate excellent word-of-mouth buzz.

Q: Should I switch from WinHelp to HTML-based help?

A: Reading newspaper headlines has given the people who make decisions on how to deliver their online help a great deal to worry about. Selecting Microsoft’s HTML Help as the standard help system is not a foregone conclusion because of Microsoft’s legal problems. The government’s decision will have a major impact on Microsoft, its competitors, and Windows help authoring in general.

Microsoft wants to make HTML Help into the Windows standard from 1998 onward. Should all help authors switch immediately, or will the decision by the Justice Department dismantle the powerful hold Microsoft has on the marketplace? These considerations are important, and making an incorrect decision now, without more information, could cause trouble for help authors and software developers in the future.

Underwhelmed recently saved a client $80,000 by following a conservative path and adopting a wait-and-see position. Our recommendation for now: continue to await the outcome of the hearings and the trial if you can, since there is no telling what changes will occur in the industry. Here are a few things to consider:

To make Microsoft HTML Help work, Windows 98 includes a core install of Internet Explorer, which remains at the crux of the matter being argued in the trial. Even though no folder or icon appears on the user’s computer, Internet Explorer still launches as the default browser when a user clicks a Web address in an email message or elsewhere.

The Department of Justice has major problems with this; there is no guarantee that HTML Help will remain a part of Windows 98 unless Microsoft finds a way to completely separate it from the use of Internet Explorer. If an application runs on Java, or is web-based or inside a browser, choose an HTML-based help system using generic HTML.

WinHelp will be a safe choice through at least the year 2001 if not later. HTML Help is part of Windows 98, but so is WinHelp. If you are developing Windows-based software and plan to continue supporting that environment alone, WinHelp is the best choice. You will have no need to consider the alternative until you move into the browser environment.

Microsoft HTML Help does not yet offer the same reliability, functionality, and stable access capabilities as WinHelp. There is a tradeoff with HTML Help, and you will sacrifice some of the functionality you can get with WinHelp. However, with a more open platform, you can reap some benefits in terms of availability and flexibility.

If your product is Java-based, the safest way to choose a help system is to create generic HTML files your programmers can link to the software by inserting additional program calls in the source code of the product. Programs like NetHelp and JELP (a Java-based help program) are some of the available options depending upon your software. These help systems are supposed to be platform independent. They are and they aren’t, and Underwhelmed has the experience necessary to assist you in determining the right choice for your product.

Q: Should I ship online versions of documentation on a CD-ROM?

A: It is a good idea to include Adobe Acrobat PDF versions of printed guides on CD-ROM; this makes it possible for users to print single chapters and take them home to read, or for travelers to access the contents of the guide on their laptops without lugging heavy printed materials around in their briefcases. It is a bad idea to substitute PDF versions of documentation for a true help system. PDF is not designed for this purpose, and the functionality is definitely lacking, even though PDF files are searchable and can have links.

Software users are accustomed to WinHelp-style functionality and are more likely to call technical support when confronted with a PDF-based help system that doesn’t fit the familiar look and feel of WinHelp.

Here are some excellent reasons to create a PDF version of a user guide:

To print multiple copies in formatted text: PDF versions of user guides should only be included on CD-ROM for ease of printing.

To provide a specific chapter to your company’s sales representatives, without having to print the entire manual.

Here are some terrible reasons to create a PDF version of a user guide:

To take the place of a help system. If you need to say you have online help but don’t want to develop a help system, Adobe Acrobat can provide an effective set of links between topics, but it can’t provide context-sensitive help and it is not in a familiar format.

To make another copy of the new printed guide. Users really should have a nicely bound printed guide.

To eliminate hardcopy printing costs. Printed material should not be read exclusively on the screen.

Q: Is Web-based documentation a good choice?

A: Depending on the product, Web-based documentation can provide your customers with information they require immediately. The latest versions, changes, and alterations can be uploaded daily, so the customer can access the Web site regularly to be sure they have the most accurate documentation available.

Web-based technologies provide a method for converting text into a form that anyone with a Web browser can access, read, and print. In addition to HTML, Adobe Acrobat PDF technology now offers the option of providing formatted text that can be searched and embedded with links. The possibilities are seemingly endless.

Organizations have become increasingly global in their outlook and operations. Employees must find ways to communicate with one another across time zones that are sometimes difficult to manage. Information that is vital to the job is hard to locate. Software development cycles are shortening radically, causing major difficulties in providing clients with up-to-date documentation. With the pressures of the market and a continuing focus on customer service as the way to gain and retain clients, a new way to share information and resources in a timely manner is through Web-based PDF and HTML files and other documentation sources.

Accomplishing this task requires planning and resources. Your audience’s composition, level of competence, and learning needs are only a few of the factors that determine whether Web-based documentation is appropriate for your product. Our experts can help you perform this analysis and determine whether using the Web to deliver documentation is the right choice for your company.

Q: After my project is completed, what’s the best way to keep it maintained and updated?

A: The most commonly ignored part of the documentation process is maintaining information. A plan for ongoing maintenance of your documentation should be part of your company’s overall information strategy from the start.

For a product that doesn’t change much between major releases, often just release notes and a What’s New guide are enough. On the other hand, a product that helps users work with a rapidly changing technology such as Java or XML may have enough ongoing changes to require document maintenance that makes Web-based documents a good idea.

Leveraging your investment by using the same writers who created your documentation set in the first place is the best idea. In addition to getting a good value, you’ll retain a consistent style which is incredibly important to your users. Either assign one or two of your staff writers who wrote the documentation initially to maintain it or, if you had an offsite documentation team develop your documentation, it might be best to establish a maintenance agreement with them.

The requirements vary wildly, as does everything in the world of documentation. Underwhelmed can provide the right combination of skills to help you make a good decision, and we will be around to help you as your needs change and grow.

Q: Is single-source multiple-media publishing the right solution for my needs?

A: Consider the cost benefits of maintaining one source document for the text, but having the ability to simultaneously publish it as a Web site, a WinHelp system, and as a printed user guide. The technological capability to do this involves desktop publishing software such as FrameMaker where careful tagging of specific paragraphs allows you to port appropriate text from a completed user guide to various other media. Another approach would be to use RoboHelp or Doc-to-Help with Microsoft Word, where you can port the online help source information out into paper formats, or into an HTML-based help reference or Web site.

You can also use a more sophisticated technology such as SGML or XML. These mark-up languages are increasingly being adopted by companies to provide customers who work in various computing environments with exactly the same source material.

We can provide the expertise to develop a system that your company can use over and over again. Good information architecture and knowing the tools well takes knowing the process, which is what Underwhelmed specializes in. You can save money by leveraging your investment—creating the text once, and then porting it to the various forms needed. When it’s time to update your documentation set, everything gets updated at the same time.

Q: What are the most productive ways I can use multimedia demos and CBTs?

A: The concept of multimedia presentations started with the slide show. Now we’re working with computer-based technology that is both portable and flexible. Here’s a bit of history to help you understand the way information is shared today.

Early multimedia business programs were presented by cueing a single 35mm slide projector with pulses from a tape player. This technology was developed to the point where presentations might include 20 or more projectors, big sound systems, complicated lighting effects, and multiple film or video projectors, all controlled by dedicated computers. These media events were designed to support corporate speakers, deliver corporate messages, and profoundly motivate the audience.

As multimedia migrated to the present-day desktop computer, 35mm slide-based visuals were replaced by computer presentation programs like Aldus Persuasion, Microsoft PowerPoint, and Lotus Freelance. The traditional film copystand was replaced by image-creation programs like Photoshop, Freehand, Illustrator, and CorelDraw. At the same time, Macromind was building the program that would become the core of the Macromedia family of interactive programs for the desktop and for the Internet.

Consider that the desktop computer is actually the most widespread interactive multimedia platform. One might argue that the Apple Graphical User Interface (GUI) was the first desktop use of interactive multimedia. Your customers are by now quite familiar with the interactive skills that make a CD-ROM interesting, informative, and easy to use.

In the age of the Internet, there are scores of interactive multimedia products available to serve businesses of all types and sizes. Computer-based multimedia presentations offer exciting opportunities for communication to all kinds of businesses, large and small. Your business can design exactly the right message, build a program that gets the message across properly, and all within a budget that you can afford.

How You Can Use Multimedia Today

Multimedia demo disks work effectively as direct-mail pieces. For instance, you can send your prospective customers a demo for a software product you haven’t created yet using Authorware or Director. This is a cost-effective method to front-load marketing efforts and to gather feedback along with response levels before you start development of the product. It’s also an excellent method for prototyping software. For face-to-face marketing efforts at trade shows, a multimedia demo looping endlessly can attract potential customers. Include interactivity and get your audience involved.

The interactive kiosk is becoming more and more popular. It is a multimedia device that shows off your products and services and lets the user take their own route to learning more about what you have to offer.

Computer-based training (CBT) is mainly used for education and training. Once you’ve finished developing and shipping the software, equipment, or service and want to train the sales and marketing staff, technicians, users, or the customer, you can send a CBT out on a disk and, for more utility, have links to related topics in a help system or to your Web site.

An interactive multimedia training program can use screen captures from the original application to emulate the actual user experience. Since CBTs are self-paced, you can add great features to them. For example, if the user makes a mistake more than twice, a flashing arrow pointing to the correct place to click or a dialog box describing the procedure can guide them through the process until they get it right. You can train a potential customer to use a very large networked database program directly from CD-ROM-based interactive multimedia files, without using the program or the network. This highly efficient synthesis of training and marketing is possible because user-interface screens access and control virtually all computer software products today. Training can also provide testing so users can track areas where they need to improve their skills.

Web-based training provides product information and skill development directly on your Web or intranet site. This has become an extremely popular form of distance learning. With work schedules so varied and when so many people need to increase their skill levels, it makes perfect sense to offer your software or hardware training programs on your own Web or intranet site. It increases your visibility, people appreciate the access to the information, and you also benefit by having a better-educated user population.

Q: What if I want to informally talk with Underwhelmed about my documentation needs?

A: We hope we’ve taken some of the mystery out of planning your documentation projects. Please don’t hesitate to call us at 415/289/3828, e-mail us at info@underwhelmed.com, or review the rest of our white papers and other resources on our Web site. Also, one of our project managers will be happy to assess your project onsite free of charge and answer any other questions you might have if you so desire.