TechWhirl (TECHWR-L) is a resource for technical writing and technical communications professionals of all experience levels and in all industries to share their experiences and acquire information.
For two decades, technical communicators have turned to TechWhirl to ask and answer questions about the always-changing world of technical communications, such as tools, skills, career paths, methodologies, and emerging industries. The TechWhirl Archives and magazine, created for, by and about technical writers, offer a wealth of knowledge to everyone with an interest in any aspect of technical communications.
I agree with Bill Swallow-not that we disagree on much, perhaps a question over light beer and one more over the ranking of the number one and number two best (regularly-available and reasonably-priced) gins. I'll not quote his e-mail, though. The "Differentiating Online Help from Printed Documentation" article on page 10-12 of July/August's Intercom is, well, bunk.
My intent, by writing this and posting it, is to generate interest in the article, the magazine, to spark debate, and then, to provoke you to write a letter to the editor at Intercom expressing your disagreement (or agreement) with the article. In that way, the article succeeds for Intercom, the editors, and the author on levels other than being accurate or valid. The article is not poorly written, and I do not fault Intercom's editors; like we technical writers, they probably rely on their SMEs (subject-matter-experts)-you and me-to be on-the-ball, or close to it. The problem, my issue, with the article is the premise.
My problem is that the premise of the article, as stated in the opening two paragraphs is blatantly false. After that, the article really can do nothing to redeem itself-the article's credibility hinges on you buying into the debunking of single sourcing as a method for creating online help.
I am willing to stipulate the following, so we can focus on online help and this article:
1) That printed documents are organized in a linear way and also are often used in a linear way, even though, indexes, TOCs, cross-references, thumbing through, and hypertext and bookmarks in online books might be examples of non-linear use (and following a thread of hypertext in a non-linear help file might be deemed . . . linear).
2) That single sourcing can be used for more than just creating online help and a printed document from the same source, that it can be used to output a variety of deliverables from a single set of source files.
3) That single sourcing is not always appropriate.
In the opening paragraphs, the author of "Differentiating Online Help from Printed Documentation" tries to validate the article by using two alleged myths to invalidate single sourcing as a means of creating online help. The problem is, the myths are a red herring and the arguments raised against single-sourcing are wrong-they are myths in and of themselves. Furthermore, the repeating of these inaccuracies in the article compounds the issue.
The author writes, "The first myth is that a single design suffices for all types of documentation. The truth is that you cannot organize online help in the same way you organize a printed guide. The linear format of printed material does not work for online help, which requires you to chunk information in individual topics. Users move through the system by clicking hyperlinks, a method of navigation that does not rely on linearity."
The author also writes, "The other myth is that you can use single sourcing to convert a printed document into quality online help."
The author goes on to claim, "However, when you single source, the document you deliver does not meet the unique criteria for each documentation medium. Converting a manual to PDF is an easy way to deliver printed material and enables users to easily access cross-references. But, a true online help system is not linear, and you cannot create it from a printed guide without modifying the layout to meet the unique medium of online help."
These attempts to invalidate single sourcing are patently false and, since they are the premise and keystone to the entire article, the article fails. The premise fails for the following reasons:
1) Single-sourcing does not begin with printed output. Single-sourcing begins with a successful design that considers all of its deliverables, often including both printed output and online help. A process called repurposing might begin with printed output, but that is not single-sourcing.
For example, after you create your content in your single-sourcing framework, you decide what to output. You might choose to output online help first--or output both simultaneously (if your hardware supports it).
There are two popular approaches to single-sourcing currently being used: database and super-set document. The latter, exemplified by FrameMaker and WebWorks Publisher Professional, requires the creation of a document that holds all the content, and you parse-out content as needed and by design to the deliverable (deliverable being online help, online PDF, PostScript for press, etc.). Both methods let you control content, as well as chunking, look, feel, and navigation.
2) In what way does organizing online help in a linear way affect the use of online help? I submit, it is common to organize even traditional, multi-sourced (non-single-sourced) online help in a linear way, for ease of authoring, editing, updating, organization, and sanity.
For example, when authoring online help, do you randomly choose topics to write about and write about them in that random order? I expect that would make it easy to miss a topic or two. Or, do you assign topics a random number, and then order them by number to create the non-linear content; do you add the links before or after you randomize the order? If you randomize the topics first, say 1,700 topics in a random, non-linear order, how do you easily identify the source and destination of hypertext links?
Instead, I submit it is more efficient and your writing is more accurate if you organize your online help, in RoboHelp or wherever, in a linear way, based on the order features are accessed in the software or the way you expect the user to use the product. I further submit that writing your online help in a linear way in RoboHelp, or as part of a single-sourcing project, has little to no affect on how the reader uses the help.
Use of online help is determined by use of hypertext, visual clues, content, accuracy of index, and search functions. Single-sourced online help can accommodate this kind of random access just as well as multi-sourced online help.
Certainly, drawing from a single-source database is less linear than writing online help using a traditional HAT (help authoring tool). But, even if you draw your online help from good ol' linear FrameMaker, the hypertext, chunking, index, search, and so forth can easily promote non-linear use of the resulting online help file.
3) Online help is not PDF, though I agree it can be-see FrameMaker 5.5 online help-but such use is rare (I must note that a simple template change can turn an 8.5x11 or A4 document into a screen-happy 4:3 ratio). Generally, folks who are single-sourcing are creating cross-platform HTML-based help, JavaHelp, HTML Help, and WinHelp, the self-same formats that multi-source workflows are creating.
4) Single-sourcing via a super-set document or database can be poorly done, just as multi-source, traditional RoboHelp-esque online help can be poorly done. And, both types of workflow suffer for many of the same reasons: a lack of time, lack of staff, and lack of funds.
Like successful multi-source online help, single-sourced online help can succeed. Single-sourced online help can be context sensitive, use pop-ups, etc., and be functionally the same as multi-sourced online help. As with multi-sourced online help, single-sourced online help is as good as you choose to make it. Single-source templates reflect the time, effort, and skill you put into them. And, single-sourcing workflows can have a supreme advantage when it comes to resources: for repeated projects and projects that share content, single-sourced online help will save you time, staff, and money, while delivering at least the same quality as your multi-sourced project. In fact, I'd say a single-sourced online help project offers a chance at better quality, because your authors can focus on content instead of fretting the formatting, and, since only one set of source files are maintained, you don't have to worry about synchronizing multiple sources with the same, updated or new data.
5) In "Differentiating Online Help from Printed Documentation", the author points to specific things that are used in the online help medium, including: 4:3 screen layout, use of specific fonts, use of color, and use of hypertext. Single-sourced online help can take advantage of all of these, and be different than printed output single-sourced from the same content.
Had "Differentiating Online Help from Printed Documentation" discussed techniques and approaches to differentiating online help from printed documentation on the merits, then the article could have been successfully applied to online help created from both single-sourced and traditional multi-sourced workflows.
However, as is, the document's credibility hinges on debunking single-sourced online help and single sourcing. Because the document's arguments are false, it fails.
I recommend you all read the Intercom article in question, so you can consider the article in its entirety rather than by the snippets and opinions I post. Then, I recommend you send a letter to the editor and share your thoughts: intercom -at- stc -dot- org -dot-
Cheers,
Sean
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Your monthly sponsorship message here reaches more than
5000 technical writers, providing 2,500,000+ monthly impressions.
Contact Eric (ejray -at- raycomm -dot- com) for details and availability.
Buy RoboHelp Deluxe starting at only $798: you'll get RoboDemo, the hot new
software demonstration tool that's taking the Help authoring world by storm,
together with RoboHelp Office. Learn more at http://www.ehelp.com/techwr-l
---
You are currently subscribed to techwr-l as: archive -at- raycomm -dot- com
To unsubscribe send a blank email to leave-techwr-l-obscured -at- lists -dot- raycomm -dot- com
Send administrative questions to ejray -at- raycomm -dot- com -dot- Visit http://www.raycomm.com/techwhirl/ for more resources and info.
