|
|
|
|
|
Producing online and printed material need not be a chore where wording and content are tailored to the medium. Single-sourcing not only saves time and effort, but also allows both mediums to improve from the documentation effort. Printed material can benefit from the personal 2nd person language and terse writing style of online material; online material can benefit from the completeness in organization and navigation of the printed material.
The best of both worlds (print and online) can be approached.
Write and organize the documentation with PDF (print) as the initial target even if ultimately intended for online uses (WinHelp, MS-HTML Help, HTML, etc.)
This forces more thought into document structure, document organization, topic grouping, topic chunking, topic layout, topic wording, etc.
This can force more thought into the content, because you are primarily concerned about a linear structure rather than the hyperlink plumbing required to make a bells-and-whistle online version.
A reference chapter that is organized alphabetically is still organized.
You should plan to provide support for linear browsing that can hit all topics from beginning to end.
Overlay the plumbing for online help (e.g., content IDs, URLs) on the documentation (e.g., markers in the source document) to hyperlink the application to the relevant information in the documentation.
Plan for banner topics (e.g., displayed with a non-scrolling region in WinHelp) rather than pop-up topics.
Banner topics allow for better navigation, because navigation buttons (Contents, Index, Browse, etc.) are present.
As part of the movement for responsible use of pop-up topics, encourage the software engineers to have Content-IDs assigned to all widgets in the interface, but have them change the API function call to one that displays banner topics instead of pop-up topics.
Map, alias, and route links to the same banner topics or to mid-topic locations as appropriate.
The technical writer should be making the decision when pop-up topics are used where they make the most sense (such as definitions.)
You deliver PDF in addition to your other content-sensitive help. Why?
If you deliver PDF, you can reduce the number of printed pages that you have to produce and ship. The costs are pushed to the customer, but is a direct savings to your organization.
PDF files print better than topics from WinHelp or a browser.
PDF files are laid-out for print and permit printing of entire manuals or ranges of pages.
With minimal up front planning, each topic in the online help can directly link to its associated PDF file.
Printed manuals may not always physically remain with the installation machine over time. Online information is often more closely coupled with its associated software application or hardware in terms of hard-disk location. Hence, online information can remain accessible as long as the application remains installed and working.
Dont withhold information. Bits are small and CD-ROMs hold lots of them.
If your readers dont find the information that they need, who are they going to call? Ghostbusters? Or your expensive customer support department.
The entire, complete documentation suite can be published and distributed on CD-ROMs. Updates can be made available over the Internet.
The index/concordance does not have to be limited in its comprehensiveness, because online pages load fast, scroll easy, and can be searched.
An index is not the same thing as a full-text search. Full-text search is not under the technical writers control, provides more topic misses than hits, and can be cumbersome to use (e.g., every other click is the browsers Back button.)
Note: Paraphrased from Jared Spool and User Interface Engineering:
The more times the users searched, the less likely they were to find what they wanted.
The data is quite clear on this: On a single search, users found their content 55% of the time, whereas users who searched twice found their content only 38% of the time. None of the users in our study who searched more than twice ever found their target content...
Theoretically, as people use the search engine, they should get better at making it perform. After all, each successive interaction is a learning moment -- something that is teaching them the idiosyncrasies of the tool...
But that's not what we've seen. Either users succeed up front, or things go downhill rapidly.
|
|
|
Open-Source tools compliments of Voyant Technologies, Inc. and Glenn C. Maxey.
01/13/2003
TP Tools v2-00-0a
# tpt-hug-02