documentation style

Matt, I see you've been getting a lot of feedback on this one.

I'm with you in that I expect to be able to put information together to figure out what to do with it. Tutorials are fine for the idea of "learning by doing" and showing what a work flow should generally look like, but they leave so much information out. I prefer a concise description of the facts, with illustrations or examples as necessary.

In the case of software documentation, I'd like to see a description of what a tool does, what it's capabilites, limitations, and oddities are, and then an example of how to use it. I find utterly useless documentation which says things like "Press the button marked 'widget' to activate the widget option." I see too much of that.

Give me "Machinery's Handbook" over "Machinery for Dummies" any day.

matt wrote in news:hQesg.3060$pB.325@trnddc06:

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.

Dale Dunn wrote:

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

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 this should not be necessary. To use a SW example, we shouldn't have Ed Eaton (a user) distilling years of experience with the loft command to let us know about some of the obscure features and behaviors. That should all be documented and available.

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.

matt wrote: