LOGIN | REGISTER NOW | SUBSCRIBE
 
 
News on Monday
more>>
SharePoint Tech Report
more>>


   

 
 
Download Current Issue
ISSUE 7/1/2009 PDF

Need Back Issues?
DOWNLOAD HERE

Receive the print Edition?


 
Is the mystery Borland suitor Serena?
Borland software is considering an offer from another company after a preliminary deal with MicroFocus. Is Serena the new company?
06/30/2009 01:55 PM EST

Windows 7 - An eBayer's dream product?
Windows 7 pre-orders can make people money on eBay.
06/29/2009 03:48 PM EST

Know thine cloud provider
Cloud computing require companies to understand compliance and regulation. Third parties will play a big role in regulated industries.
06/29/2009 02:58 PM EST

 

Microsoft Worldwide Partner Conf.
7/13/2009 to 7/16/2009
New Orleans
Microsoft

OSCON (Open Source Convention)
7/20/2009 to 7/24/2009
San Jose
O'Reilly Media

XBRL Technology Workshop & Summit
7/28/2009 to 7/30/2009
Santa Clara
XBRL US

ACM SIGGRAPH
8/3/2009 to 8/7/2009
New Orleans
ACM SIGGRAPH

OpenSource World (formerly LinuxWorld)
8/12/2009 to 8/13/2009
San Francisco
IDG World Expo


 
print Printable version 
Most Read Latest News Blog Resources
Kapow automates website data retrieval
Kapow Technology's Web Data Server 7.0 can be used to create modules that navigate through...

COBOL’s future lies in the clouds
After 50 years of use in businesses, COBOL is still lingering around mainframes. But the s...

Oracle's Fusion 11g lays groundwork for ERP platform
Fusion's components are standards-based and integrated, but some abilities are lost if non...

Digg!  Digg
Reddit  Reddit
Slashdot  Slashdot
Share on facebook  Facebook
Share on Twitter  Twitter

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
 

Add comment


Name*
Email*  
Country     


  • Comment
  • Preview
Loading