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.
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:Robert Lauriston <robert -at- lauriston -dot- com> To:techwr-l -at- lists -dot- techwr-l -dot- com Date:Thu, 5 Nov 2009 10:06:11 -0800
As I've noted in a couple of posts, I understand that you're referring
only to procedural content.
That you say "procedural documents" rather than "procedural topics" is
one clue as to how differently we think about these matters. The
content of my online help is usually identical to the user guide
(since both are generated from the same source), and includes
conceptual topics, reference topics, and other non-procedural
topics--generally, everything except the release notes and
installation guide.
When telling a user how to perform a task, you don't want to go into
long conceptual digressions, 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.
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.
On Thu, Nov 5, 2009 at 6:37 AM, Keith Hood <klhra -at- yahoo -dot- com> wrote:
> Once again, I must emphasize that when I wrote about my thinking on what to put in a technical document, I WAS REFERRING ONLY TO PROCEDURAL DOCUMENTS. As in documents that tell the user what steps to take in order to perform actions with the item, as opposed to documents that tell the user *about* the item. You seem to be unwilling or unable to understand the distinction.
>
> The questions about why a user would want the thing and what they hope to accomplish with it, and the effect the answers have on the document being produced, are variable. They depend on the type of document being done. A white paper is almost completely based on thinking about business aspects of how the thing fits into the user's business model. Online help is almost completely based on thinking about how the thing is used as a tool.
>
> It is NOT a one size fits all matter. There is a spectrum of concern when thinking about what to put in a document and how to arrange it. On one end of the spectrum, an executive summary is almost entirely - to coin a phrase - marketing speak, and on the other end of the spectrum, a quick start card is almost entirely tech speak. Their natures are so different, the writer must consider different factors when writing them.
>
> The reader of an executive summary does not care which button the user pushes in order to do something. He cares about how the thing will improve his business situation. So deciding what to put in his document is weighted toward the business end of the scale. The user who is trying to employ the item to accomplish some task and is in a hurry is very much concerned about which button to push next, and he could not possibly care less what business advantages his boss sees in the thing. So deciding what to put in his document is weighted toward the technical end of the scale. And since there are significant differences in what those people will want and need in their documents, the questions to ask about what information to give them will be different, and the types of answers formulated for those questions will be different.
>
> It is a matter of asking different questions for different documents, because they do not serve the same purposes, so the thinking about how to structure them is different.
>
> How many different ways do I have to state it before it finally gets through?
>
>
> --- On Wed, 11/4/09, Robert Lauriston <robert -at- lauriston -dot- com> wrote:
>
>> From: Robert Lauriston <robert -at- lauriston -dot- com>
>> Subject: Re: Doc Design and Convention ( was TECHWR-L Digest, Vol 48, Issue 27)
>> To: techwr-l -at- lists -dot- techwr-l -dot- com
>> Date: Wednesday, November 4, 2009, 2:58 PM
>> I agree that a good technical writer
>> should think that way. It's not
>> either/or: that's one of the places where our work overlaps
>> to some
>> extent with marketing.
>>
>> I said that in response to Keith Hood, who seems to be
>> arguing against
>> it. That's a substantive issue, not semantics:
>>
>> "... it seemed to me your thinking about the users was more
>> closely
>> related than mine to the way in which a marketing person
>> would think
>> about the users. Your second question was, "For what
>> purposes are they
>> buying and using the product?" That's broader in scope than
>> the kind
>> of questions I ask, and seemed to indicate thinking about
>> how the
>> users see the item fitting into their business. That way
>> of
>> considering user concerns about the item isn't related
>> strictly to the
>> technical aspects of the item. When I think about why users
>> may want
>> the item, I tend to consider it more as a matter of tool
>> use. I think
>> my way of looking at user needs and concerns is more
>> tightly focused,
>> that's all. And please remember that I'm talking here only
>> about doing
>> procedural documentation. For reference materials, or for
>> documents
>> that are more business related, like requirements or white
>> papers, my
>> approach to deciding what to put in the docs would look
>> more like what
>> you and Paul wrote. ..."
>>
>> On Wed, Nov 4, 2009 at 11:37 AM, Gene Kim-Eng <techwr -at- genek -dot- com>
>> wrote:
>> > It would appear we only have a semantics issue.
>> >
>> > I don't see creating documents that "reflect the
>> specific business
>> > requirements of prospective customers and a contextual
>> understanding of how,
>> > by whom, and for what purposes the product is used" as
>> thinking like a
>> > marketer. I see it as thinking like a technical
>> writer.
>> >
>> > Gene Kim-Eng
>> >
>> >
>> > ----- Original Message ----- From: "Robert Lauriston"
>> <robert -at- lauriston -dot- com>
>> > To: <techwr-l -at- lists -dot- techwr-l -dot- com>
>> > Sent: Wednesday, November 04, 2009 11:01 AM
>> > Subject: Re: Doc Design and Convention ( was TECHWR-L
>> Digest, Vol 48, Issue
>> > 27)
>> >
>> >
>> > I didn't say anything of the sort. Marketing hype
>> doesn't belong in
>> > technical documentation. I never use any marketing
>> language except
>> > sometimes in the first few paragraphs of a user's
>> guide and release
>> > notes, and even there I tone it down and cut anything
>> that's not
>> > supported by the facts.
>> >
>> > Documentation that reflects the specific business
>> requirements of
>> > prospective customers and a contextual understanding
>> of how, by whom,
>> > and for what purposes the product is used is a helpful
>> tool for anyone
>> > evaluating the product, especially when installation
>> is a long and
>> > complex process (as is usually the case for
>> client-server and
>> > Web-based applications, especially those that require
>> a third-party
>> > database such as Oracle or SQL Server). It helps the
>> prospective buyer
>> > understand whether the product would meet their
>> needs.
>> >
>> > I know that's true from the buyer's side as well. If
>> it's too much
>> > trouble to install a product and I can't tell from the
>> docs whether it
>> > will do the specific things I need it do, I'll move on
>> to the next
>> > candidate.
>> >
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
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-
