Content Pages:
Services:
Front Door
Document Mgmt.
Web Content/Design
»Software Doc.
Style / Single Source
About S&C:
Front Door
Mountain Relocation:
Front Door
Quick-Reference:
Front Door
Archive
Front Door
Navigation:
Site Map
Site Index
Site Search
Software Documentation Services
Scribble & Count began writing software documentation (WinHelp) in late 1994. On this page, we want to stress two important aspects: usability (including early involvement of the tech writer) and single sourcing.Making Documentation Effective
Much of the documentation that accompanies software programs is rarely used because its unusable. There are four primary causes for this:- Tech writer is brought in too late (or not at all).
- Audience is not defined.
- One approach is used, rather than multiple (structural, procedural, conceptual, reference).
Late Involvement of Tech Writer
Bringing in a tech writer late is just barely better than not using one at all. Qualified Technical Communicators are among the best qualified usability experts, and they should help design the interfaces. Experienced tech writers can read code and/or specs, and can begin work early in the development process. And having the writer on the scene early uncovers bugs when they are less expensive to fix. In the long run, experienced professional communicators onsite early pay for themselves in efficiency and quality.We know usability, and can assist in interface design; we can read code and specs, and can document vaporware; we're no substitute for good test scenarios, but we've added a lot of bugs to the database.
Lack of Defined Audience
Most documentation is produced with little or no time spent identifying the audience:- Beginners, or experts?
- Managers, or operators?
- Age? Education? Preferred language?
- Conditions of use?
Of course, S&C's partners have been writers, teachers, and researchers/librarians.
Single Approach to Documentation
Some users open the documentation to perform a task; some use it to get the "gist" of the software; some want to see how it's structured. Each is different. All are valid.| Note: | One person can be different users, wanting an overview first, then task help. The expectant user who opens the installation guide is not the frustrated user who opens the troubleshooting appendix after the program crashes. |
With object-oriented topic types or class designators assigned to "chunks" of text (see our Document Conversion / Single Sourcing service), you can create one master document and compile customized subsets that address these different needs and moods.
| Example: | An introductory "chunk" can have links to task, concept, or reference chunks. If you know your audience well enough to address their needs. |
Single Sourcing
Consider all of your software documentation. What do you produce:Media: Print? CD ROM? Online? Classroom?
Content: Procedural? Conceptual? Reference?
Single sourcing can produce real efficiencies when:
- You are producing for more than one medium;
- Your audiences are clearly defined;
- Your styles are explicit, consistent, and compatible;
- Your authoring and production software support it;
- Your writers have the breadth of experience to produce it;
- Your production schedule allows it.
Top
Rev. 11-Nov-01
Related Options:
Services Front Door | "Audience Analysis" essay | About S&C
Scribble & Count™ LLC
PO Box 1490 Idaho Springs CO 80452
303/567-4646 (v) 303/567-4644 (f) 303/570-1044 (c)
Webmaster © Scribble & Count LLC 1994-2004