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.
It basically costs nothing to generate and deliver the PDF along with
the online help, so why not? Some users may never look at it, but
others may appreciate having a format that prints better.
Among other things, PDFs can be a helpful presales tool, since
prospective customers can skim them without having to install the
On Thu, Jul 23, 2009 at 9:22 AM, Deborah
Hemstreet<dvora -at- tech-challenged -dot- com> wrote:
> Hi Robert, and Geoff,
> Thanks for your in-depth replies. The seem to support my thinking, but
> helped me picture better what I want to do and where I want to go.
> Robert, what is your take on how users handle the PDF? My client says they
> are not convinced the user will read a 30 page PDF with all of the
> conceptual information in it. They feel it will probably be more accessible
> in the help.
> I have mixed feelings. I believe we need both (and am planning on this).
> Well, back to work!
> P.S. and thank GOD I have work!
> Robert Lauriston wrote:
> In one doc I'm particularly happy with, I have an introductory
> reference topic that outlines the typical workflow. There are 30 steps
> in the workflow, and each has cross-reference hyperlinks to detailed
> how-to topics for specific tasks. For example, the first step is
> "Create a new project file," which has a link to an overview topic
> "Creating Project Files." This topic includes whatever general
> information the user might need to know about creating project files,
> followed by links to how-to topics for all the various ways the user
> do that (create a blank project, create a project from a template,
> retrieve a project from the server).
> When helpful, how-to topics start with prerequisites, as Geoff
> describes. They may contain links to the workflow outline or other
> how-to topics to help the user figure out what to do next. The how-to
> topics are grouped and sequenced along the same lines as the workflow.
> Within the workflow, there are many conditional branches and iterative
> loops. For example, step 17 is a unit test for one element of a task,
> and a project may contain many tasks. If the output from the test is
> wrong, the next step is to debug; if the output is correct, the next
> step is to add another element to the task (go back to step 11), or,
> if all elements have been added, to test the complete task with live
> data (go on to step 18).
> How-to vs. tutorial: A how-to topic covers a relatively simple
> low-level user task, such as creating, saving, or deleting a file
> ("using a dialog box" is NOT a task), and is intended to assist people
> using the product to do real work. A tutorial covers a relatively
> complex high-level task with many steps, typically from the creation
> of a file or opening a sample file through to final output or
> completion, and is intended for new users and people evaluating the
> product (so tutorials have more of a marketing function than how-to
> topics). Tutorials should reflect best practices and be supplemented
> by one or more sample files.
> I always deliver the online help as a PDF user guide as well.
> On Thu, Jul 23, 2009 at 6:07 AM, Deborah
> Hemstreet<dvora -at- tech-challenged -dot- com> wrote:
> Hi All,
> I'm trying to think out of the box, and but my box has chains...
> When working on online Help, how would YOU distinguish between the pure
> HOW TO (delete, add, use a dialog box, etc.)
> Why would I ever want to do this to begin with. Conceptual information
> that, without knowing this up front, you'll never know you NEED to add,
> delete, etc.) ...
> Free Software Documentation Project Web Cast: Covers developing Table of
> Contents, Context IDs, and Index, as well as Doc-To-Help
> 2009 tips, tricks, and best practices.
> Help & Manual 5: The complete help authoring tool for individual
> authors and teams. Professional power, intuitive interface. Write
> once, publish to 8 formats. Multi-user authoring and version control!
> You are currently subscribed to TECHWR-L as dvora -at- tech-challenged -dot- com -dot-
> To unsubscribe send a blank email to
> techwr-l-unsubscribe -at- lists -dot- techwr-l -dot- com
> or visit
> To subscribe, send a blank email to techwr-l-join -at- lists -dot- techwr-l -dot- com
> Send administrative questions to admin -at- techwr-l -dot- com -dot- Visit
>http://www.techwr-l.com/ for more resources and info.
> Please move off-topic discussions to the Chat list, at:
Help & Manual 5: The complete help authoring tool for individual
authors and teams. Professional power, intuitive interface. Write
once, publish to 8 formats. Multi-user authoring and version control! http://www.helpandmanual.com/
You are currently subscribed to TECHWR-L as archive -at- web -dot- techwr-l -dot- com -dot-