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

[Robert Lauriston <robert -at- lauriston -dot- com>]

I was talking about procedural topics too.

Here's a real-world example. I was writing docs for an
extract-transfer-load utility (a tool for sucking data from one or
more source databases, processing it however, and pumping it into one
or more target databases). The primary use for ETL tools is to
populate data warehouses. However, when I talked with the product
manager, I found that only maybe 40% of the customers were using it
for that purpose. There were two other common uses (one was one-time
conversion from one system to another, can't remember the other), and
a bunch of unique cases.

That knowledge influenced the examples I used in my procedural topics,
diagrams, screen shots, sample projects, and tutorials, and led me to
add some additional tips and cautions I would not have thought to
include if the use had been strictly for data warehouses.

On Wed, Nov 4, 2009 at 9:42 AM, Keith Hood <klhra -at- yahoo -dot- com> wrote:
> I cannot emphasis this strongly enough:  When I wrote about what I thought of when deciding what to put in a doc, I was speaking specifically about PROCEDURAL documents. That means things like online help and software user guides, things that are intended for the specific purpose of telling the user how to do things. I approach the matter of deciding what to put in those as a matter of thinking about tool use, because those documents are about tool use. Such things can be a kind of marketing ploy but their primary purpose above all else is to tell the user how to do things.
>
> If I were writing a reference document I would provide background information instead of do-this-do-that procedures. If I were writing a white paper or an executive summary the audience would be different and my consideration of what to put in the document would be different. If I were drawing network topology diagrams I would ask only one question: what does the network look like? When I set down that list, I was not advocating a one size fits all approach. I was talking about thinking on the subject of making how-to procedural papers. I now seems to me I didn't make that clear enough. Maybe in the future I'll try all caps.
>
> That said, I disagree with your last statement. I am a good technical writer - I've been doing it for 20 years - and I don't think like a marketer. Thinking like a marketer is the marketer's job. It's my job first and foremost to ensure the document - whatever flavor it is - serves the customer's needs for technical guidance, and then to try to satisfy the other stakeholders. My job where marketing is concerned is to coordinate with the marketer and the manager to ensure the resulting documents have the right look and feel, and language, to help support marketing concerns, but are still usable as technical documents. If the document is based entirely on marketing concerns, it's not a technical document, it's a white paper. That's a different kettle of fish and different concerns apply.
>
> As for excluding industry-specific warnings and things like that, that may be a problem if I were writing about industry-specific things and I forgot. But I don't think there are any industry-specific warnings to put in brand new software that's never been seen before and doesn't apply to any particular industry. Such warnings are almost never a concern for me.
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

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- 

To unsubscribe send a blank email to 
techwr-l-unsubscribe -at- lists -dot- techwr-l -dot- com
or visit http://lists.techwr-l.com/mailman/options/techwr-l/archive%40web.techwr-l.com


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:
http://lists.techwr-l.com/mailman/listinfo/techwr-l-chat