documentation style

I've been reading though a lot of documentation recently, and notice a
few things about how information is typically formatted. I'm usually
looking for information formated as facts or lists of facts. I figure
I'm bright enough to string the facts together into actions. Tutorials
are nice, but they kind of show the "drive-by" version. They don't
always talk about why you do this or that, you get a single perspective
on what is usually a multi-functional tool.

What do you find most useful? Do you want to know what the tools do, or
do you just want to see some random example of them being used? Desk
Reference or scripted tutorial? Several small, focused examples or one
large example that covers a range of issues artificially linked together?

I know, I'm asking the question in an unfair way, but I'd just like to
hear a few arguments one way and the other for different types of
documentation. Examples of what you think good stuff looks like would
be helpful. I guess I'm talking about professional "stuff" rather than
homegrown.

 

Ok, but what part of it do you leave out. If you want the unabridged
version, it should say that the widget option can be started with the
toolbar button, with the menu item, with the RMB option, or with the hotkey
of Alt-W. The simple things are important to the beginner.

I find tutorials good in that they show capabilities. They are good for
step by step walking through for someone that doesn't know the
functionality, and as quick reminders. Then I challenge people to go back
and recreate the object without the book - can you do it? If not, go figure
out what you missed.

Personally, I find the SW Help to be quite good. It has lots of examples,
good pictures, good hyperlinks, and just about everything that I want to
find seems to be covered. And the API help is good in that it spells out
all the parameters of a particular command, and a lot of the time, provides
some kind of example. On the other hand the ACAD Help, in my opinion, is
not as good. I'm sure part of it is that I don't know that software very
well, but when I need to find something, I find it difficult at best.

I also like the Microsoft style in that it gives you a chance for the simple
version, and then you can expand on it. I can search the local Help, or let
it expand to the Microsoft site for a bigger picture. However, I also turn
all of my menus on full as a quick reminder of what's there - helps me
expand my usage.

I guess my choice would be that the Help would already know what level of
info I am looking for, and provide that for me. If it can't do that, then
more is better because it gives me the opportunity to dig as much as I need.

WT

 

Dale,

Yes, it has been a real hot topic. Feels like shouting down a well. I
should have said I had a mystical experience with some imagined bug or
another, and I would have been flooded with responses.

Anyway, thanks to you and Wayne for the responses. I'm finding that
writers (or is it publishers) tend to speak using verbs when only nouns
make sense. I'm not talking about SW documentation here, I'm talking
about the big 1000 page plus "how to" software books.

I've found in the past that when marketing people write marketing stuff,
they write it for other marketing people, not for their audience. When
lawyers talk, they don't talk to people, they talk to lawyers. Maybe
tech writers are the same. Someone in a starched white shirt and corner
office wants a book to feel active, so they fill it with action words
and doing rather than well organized and dense information. It winds up
making what in reality a very parallel set of data (lots of ways to do
any one thing) into something extremely linear and one dimensional.

Because of the size of some of these books, I'm imagining that the
tendency of big corporations to completely misunderstand what
individuals want is what's at play here.

 

I much prefer factual info, with a list of options, limitations and exceptions for a given
tool. Scripted tutorials don't do much for me -- I'm more interested in how a tool works and
*why* I should pick this or that option.

I want documentation to be like Keith Pedersen's presentations: lots of insight into what's
going on behind the scenes.

AW

 

OT a bit here, but not totally. If you want the *why* you need to come to
the Kansas City Summit to hear my sheet metal presentation. The focus is
centered on looking at the options and *why* you should choose a particular
path vs. another path based on the info available.

So, it's not off-topic for this thread because that appears to be the tone
here - we want to know why something is proper, not just what button to
push. That's also why I decided on that focus for the presentation.

WT

 

That's part of my gripe with contemporary documentation.
Presentations like

Contemporary documentation? Yeah, back in the '60s we had it so much
better...;o)

I know what you're saying. I think the problem is that the people who
write the documentation tend to be writers instead of engineers, which
on some levels is a blessing because engineers are typically illiterate
unless you're talking numbers and pictures.

My biggest gripe is an example like multi-body solids or in-context
design. A tutorial starts you at one end and waltzes you straight
through to the other end. No side trips, no nothing. I would rather
have a list of what the function is capable of, what its not, pros and
cons and let me figure out how to push the buttons.

I usually don't care *how* the thing works, figuring out how "should" be
a matter of good interface design. I'm more interested in *why would I
chose this instead of that* sort of information.

 

I've always gotten the impression that the documentation was poor on
purpose. If it was too good, who would buy the training classes? SW
has better documentation for the classes than what is available with
the software, but you cannot buy it without the classes. It still
isn't great, however.