Re: Opinions, please: Document by the Component or by the Tab?

["Lin Sims" <ljsims -dot- ml -at- gmail -dot- com>]

Everyone working on the development of the product CAN tell me what it
does. The problem is that I am new to the company and the product, and
the developers are, literally, the only source of information I have
other than my private sandbox.

While they expect to create specs & requirements in the future, right
now ALL the information about this product is in their heads.

I do have access to a fully functional version of the product in my
own private sandbox, but that doesn't mean I can work out everything
about how an admin would approach using it just by playing around with
it. Luckily for me, they are wonderful about answering questions
promptly and explaining things ad nauseam, if necessary.

When I said an analysis was needed, I meant that I needed to analyze
how to document the product logically and usefully. Let me give you an
example.

Today I've been working on logging information.

Logging can be turned on in multiple components and tabs, because the
developers chose to put control of logging on the same tabs that deal
with the information and events being logged.

Turning on logging for when a particular cache is accessed, for
instance, is on its own component (no tabs), but turning on logging
for when the user interface makes an API call is on a tab on a
different component altogether.

Configuring how much information is logged, at what level, and where
it's logged to is off on its on tab, however, and there's a shortcut
on yet another component that lets you see the log file on your screen
without having to open the software file (if you happened to turn on
logging to a software file, otherwise you see the RAM file
contents--if you turned THAT on).

I haven't even found out all the places that logging for something can
be turned on yet.

So yeah, I'd love to put all the context and instructions on what can
be logged, where and how it's saved, and how to get access to it in
one place. I don't really have time to corral that information right
now, so what I'm doing is a lot of "Refer to <xyz name> on page <##>
for more information."

I have plans for the future, of course, but for now, a non-task based,
reference type guide will have to be good enough.

Lin

On Wed, Oct 1, 2008 at 2:55 PM, Gene Kim-Eng <techwr -at- genek -dot- com> wrote:
> I wouldn't discount the possibility that task-based
> documents might not be desired by a product's
> users.  But I would still maintain that everyone
> working on the development should still be able
> to tell you what the most common tasks are
> without having to go away and perform some
> kind of "analysis."  How do you develop and test
> a product, much less document it, if you don't
> know what it's supposed to do?
>
> Gene Kim-Eng
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

ComponentOne Doc-To-Help gives you everything you need to author and 
publish quality Help, Web, and print content. Perfect for technical 
authors, developers, and policy writers. Download a FREE trial.
http://www.componentone.com/DocToHelp/

True single source, conditional content, PDF export, modular help.
Help & Manual is the most powerful authoring tool for technical
documentation. Boost your productivity! 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.