The First Line of Support

By Eric Butow

April 15, 2006 —

You may have had this conversation with your software development team once or a hundred times before:

You: “We need documentation for our software so our users will know how to use it.”

Developers: “But the software is so easy to use, we don’t need any documentation!”

A rejoinder to this argument can be hard to come by, because the developers are right—if your development team members are the only people using the software.

The reality is much more complicated. As graphical user interfaces (or GUIs), such as Windows and Mac OS, became popular in the 1990s, it was assumed that since users would now be using a standard interface, people would be able to use any software at all. However, a new interface didn’t solve an old problem: Application software usually brings new ways of doing tasks along with it, and users need to be told how to perform those tasks. Without any guidance, users will use their own judgment, for better or worse, to get something to work the way they feel it should work—for example, users who broke CD-ROM drive trays when they used the trays as cup holders.

Customer support costs account for as much as 60 percent of a high-tech company’s total costs. Documentation is the first line of support for most customers, and customers usually use documentation to find the answer to a problem they’re having. The inevitable result of poor or nonexistent documentation is that more people try calling the customer support lines for help.

The company tries to mitigate the costs of hiring and training customer support staff by charging for those calls. Users, who don’t want to pay for those calls if they don’t have to, usually search on the Internet to get answers. Some users visit the company Web site for those answers, and many companies not only have lists of allegedly frequently asked questions but also online forums to ask and answer questions. However, the user may not have the answers she needs, so she has two choices: Pay and hope she gets the information she needs, or give up. In any case, the extra time the user puts into solving the problem reinforces negative feelings about your company. If you have aggressive competition, this isn’t good news for you or your team.

So where do you start when you want to create successful and sound software documentation? You need to map the documentation from beginning to end, and seven steps constitute this map.

Step 1: Create a Checklist for Your Project Team. First, create a documentation checklist that answers two questions: What type(s) of documentation does your company need to create? What information do you need for the documentation.

You may need to create different types of documentation to meet the needs of your audience. For example, your documentation may include a “quick start” guide, online help that’s accessible from the Help menu bar, and formal documentation that can be printed and/or published to a PDF file, and multimedia training simulations.

However, you won’t know what types of documentation you need until you understand the needs of your users. Since you know who the software is meant for, you should have a pretty good idea of what your users’ experience level is. Then you can put together a preliminary list of documentation to include. You will refine this list after you interview your users in Step 3.

Step 2: Define Style Sheets and Formatting. Defining style sheets and formatting conventions helps both your internal staff and your users. A defined style sheet and formatting will help your team and subject matter experts (SMEs) understand how you will structure and present information in the documentation. Your users will benefit by seeing a clean and structured presentation that is consistent in tone, style, grammar and layout.

Step 3: Interview Your Users Often. The software testing process usually includes beta testers preferred customers who test your software product and offer feedback before the software is released to the public. Take advantage of your beta testers by having them review the documentation as well. The beta testers will provide invaluable feedback.

Step 4: Create an Outline. Now create a high-level outline for each component of the documentation. For example, create outlines for online help, printed documentation and any training modules. Then circulate these outlines to SMEs as well as the marketing and sales staff. Your marketing and sales teams are excellent resources for learning what customers want and what your competition is doing.

Step 5: Draft a Table of Contents. Once you have the outline in hand, create a table of contents that compartmentalizes your information into broad heads and subtopics underneath those heads always a good idea to include sections for a glossary of terms and an index in printed or PDF user guides and online help. You may also want to add appendixes that users can refer to in a hurry, such as an appendix that contains answers to FAQs. When the draft is ready, circulate it for review.

Step 6: Acquire the Information. As you write the documentation, you will have to interview SMEs to fill in any gaps that present themselves, such as information that fleshes out a concept. Interviewing can be a tricky business, and it's always important to determine how SMEs like to be contacted and what their schedules are so you can determine what needs to be done.

Step 7: Review Thoroughly. Users will discover a poorly reviewed document right away. Therefore, it's important to have a structured, rigorous review process as you refine drafts of your documentation. The review team should include members of your project team and at least one person outside the team (for example, a sales engineer), as well as the beta testers.

Review your documentation in multiple stages to catch as many problems as possible with accuracy, style, grammar and the amount and appropriateness of information. Be sure to tie all review stages to strict deadlines so your document arrives on time and is as accurate and useful as possible.

Eric Butow is CEO of Butow Communications Group, and is a contract technical writer for Writing Assistance . He is the author of four books, including "C#: Your Visual Blueprint for Building .NET Applications."

Share this link: http://www.sdtimes.com/link/29249

News Briefs: October 15, 2008 Electric Cloud makes its product line compatible with Microsoft's HPC Server, RapidMind released add-ons for its RapidMind platform, and Fujitsu opens a subsidiary in North America.

News Briefs: July 15, 2008 Enea is named to the board of CP-TA, Teradata introduces a new version of its data warehousing tool and SOA Software upgraded its Repository Manager to accommodate its Policy Manager software.

News Briefs: July 1, 2008 Cynergy's relocation triples the size of its headquarters, Microsoft releases version 1 of its Open XML SDK, NelsonHall predicts increased outsourcing, and AccuRev and Rally team up on agile CRM.

Add comment

Name*
Email*
Country

Comment
Preview

News on Monday
more>>
SharePoint Tech Report
more>>

Download Current Issue
ISSUE 3/15/2010 PDF

Need Back Issues?
DOWNLOAD HERE

Receive the print Edition?

Google Code turns 5
Google Code Turns 5, and adds a Paxos Algorithm to make the system more stable and reliable.
03/17/2010 11:16 AM EST

Test your Visual Studio 2010 know-how
Microsoft is offering free beta certification exams for Visual Studio 2010.
03/17/2010 11:08 AM EST

Microsoft lifts the hood on IE9
Microsoft is previewing IE9.
03/16/2010 01:10 PM EST