Re: Doc Design and Convention ( was TECHWR-L Digest, Vol 48, Issue 27)

Subject: Re: Doc Design and Convention ( was TECHWR-L Digest, Vol 48, Issue 27)
From: Keith Hood <klhra -at- yahoo -dot- com>
To: techwr-l -at- lists -dot- techwr-l -dot- com, Robert Lauriston <robert -at- lauriston -dot- com>
Date: Thu, 5 Nov 2009 11:51:36 -0800 (PST)

> When telling a user how to perform a task, you don't want
> to go into
> long conceptual digressions,

And I don't. That's one of my points. I want the documents to be suited to the audience and their particular needs. That's why I ask different questions about what to put in different types of documents.

> but neither should you presume
> that the
> user will have read essential caveats and useful tips in
> some other
> topic. So business-specific cautions and tips are often
> worthwhile--though you'd want to link to other, non-task
> topics for
> more details.

Would you please point out to me the part of one of my posts where I said I made any such presumptions? See my #3 question, below.

In all documents, we all must build a mental picture of the type of user who will use the document under production. That's what audience identification is. That's why I said that we must consider what is the probable level of expertise of the audience. By the time I ask myself that question, I've already identified the audience *type.* Making sure I know who is the actual consumer of the document under production is the first thing I try to do.

Again you write about this standard warning thing. Maybe that is a serious concern for you. But as I pointed out earlier, that is almost never a concern for me. If I were writing documents that were aimed at users who work within a definable industry, I would have to take such things into account. But, as I pointed out earlier, almost all my work has been done on documents for things that are new types, where it is difficult or impossible to discern a connection to a particular industry. If I were writing a reference for a new model of electrical transformer that will be installed by workers at a hydroelectric plan, who definitely belong to a recognizable electrical generation/distribution industry, I would think about what standardized warnings would be expected. But what "industry standard warnings" am I supposed to include in documents about software that is conceived for a niche market that won't exist until my employer releases the software being
developed? What industry standards are there about writing requirements for customizing the interface on somebody else's COTS software package? For you, industry-standard things may be an important matter. For me, most of the time there is no industry to have applicable standards.

And if by *business*-standard cautions you mean cautions that are specific to that company or to the way the company wants things done, here is the applicable question from the list I wrote earlier:

3. What does the user need to know *before* he tries doing that? (Could be restated as, What are the traps the reader could fall into?)

I rest my case on that point.

> Also, as I said before, my awareness of who is using the
> product for
> what business-specific purposes often informs what goes in
> my screen
> shots, diagrams, example commands, and sample code.

Same here. Of course the CEO reading the executive summary doesn't need to see screen caps of the <Commit> button or pseudocode that shows what the button is supposed to do. He wants to see the new logo and know that it will go on every page the way he said it should.

I think I am going to post one more item, to respond to something Gene said, and them I will never post on this topic, ever again. I'm tired of beating this palomino carcass.


Are you looking for one documentation tool that does it all? Author,
build, test, and publish your Help files with just one easy-to-use tool.
Try the latest Doc-To-Help 2009 v3 risk-free for 30-days 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!

You are currently subscribed to TECHWR-L as archive -at- web -dot- techwr-l -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 for more resources and info.

Please move off-topic discussions to the Chat list, at:

Re: Doc Design and Convention ( was TECHWR-L Digest, Vol 48, Issue 27): From: Robert Lauriston

Previous by Author: Re: Doc Design and Convention ( was TECHWR-L Digest, Vol 48, Issue 27)
Next by Author: Re: Doc Design and Convention - to address Gene's take on this
Previous by Thread: Re: Doc Design and Convention ( was TECHWR-L Digest, Vol 48, Issue 27)
Next by Thread: RE: Doc Design and Convention ( was TECHWR-L Digest, Vol 48, Issue 27)

What this post helpful? Share it with friends and colleagues:

Sponsored Ads