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.
> 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: http://www.doctohelp.com/
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-
