About the Dismal State of CAD Documentation

A reader writes:

I know writing as a skill is near and dear to your heart, but I’ve yet to see any articles/opinions/blogs on the current state of CAD documentation. You know, the technical documents, User’s Guides, tutorials, and other collateral that is delivered with the software to facilitate the installation and usage of the product. What’s your opinion of this side of the technology for the average CAD user?

I feel that documentation is going downhill in general, for these reasons:

• As CAD software becomes more complex, it becomes harder to document, and with the resulting larger number of errors. 

• New hires in the documentation department don't understand the software, and write trivial descriptions.

• Internationalization means that screen grabs and illustrations-with-callouts are removed, because it costs too much to manually replace them.

• Programmers make minor changes to existing commands, which are not noticed by doc writers.

• To increase profits, printed documentation is eliminated (no concern for me, but it is a problem for some, who end up paying extra for printed copies).

• Vendors generate extra profits from training and consulting, and so benefit from ensuring documentation that remains poor.

• Small CAD vendors can't afford proper documentation. 

Having written help files and books using beta software, I understand the difficulty of writing docs when the software is unfinished and still changing. But vendors could issue a Service Pack for the help file after the software ships. 

Finally, there is the subtle difference between documentation that the doc writer thinks is well-done, and what the CAD user finds useful. That's an eternal conflict, due to differences in learning styles. 

Comments

[Dietmar Rudolph]

Having worked on almost as many software books, manuals, and help files as you did, I cannot agree more. One thing to add is what irritates me most as a software user. This is missing QA (quality assurance). Only yesterday I had to look up some topics in the Autodesk developer help files. Almost every page I visited had either incorrect information, missing information, incorrect links, incorrect translations, or was not useful in other ways. Many of these problems could have been spotted even by people who do not understand the software just by trying (links), using lists (translations) and such. Even if someone did QA the help file, they did a lousy job, sorry. To me QA of documentation is as important as QA of software - and it costs money, which seemingly nobody wants to spend any more.
Dietmar

[Matt Lombard]

If the software is getting more complex, how are users supposed to know how to use it? Has the real cost of software just gone up by the training and consulting costs?

I benefit from junk documentation, and I can say that keeping up with versions is a lot of work, but it doesn't have to be that expensive. I think CAD companies are cutting costs in wrong places.

You might as well send your programmers home if you don't document what they do. Just hire a graphic artist to put a nice sheen on the face of it, and maybe no one will notice that there isn't any content.

[Patriiick]

LINE:
Command used to draw a line

This is killing me! How can a human being write something like that, this is beyond me... (may be it's computer generated?)

[Ken Fauver]

If the software developers would document the code as they should, Port that information to a DB for use to create/update documentation, it would alot less expensive to keep up. What do you think?

[Tony]

It's not just CAD, it's just about universal - most of the documentation I have to use is pretty lousy.

Two of the biggest problems I see are:
1. Lack of non-trivial examples
2. Don't explain how the program works: how the features go together, when to use what feature, etc.

And, yes, I've been on the other side, having written several manuals for custom machines.

[Jon Banquer]

I have seen major improvement in the area of CADCAM documentation in the last year or so because of individuals like Mike Mattera who does Mastercam training:

www.tipsformanufacturing.com

I use Mastercam on a daily basis and much of Mastercam's advanced functions are not covered by video instruction! You won't find any in depth video instruction on Mastercam's 4th and 5th axis simultaneous milling and it's badly needed! Same with how to use Mastercam's post constructor / editor.

Steve Wilson of CIM Integrators does video training for DP Technologies Esprit

http://www.cimtulsa.com/

Even though I don't use DP Technologies Esprit (I'd probably be much better off if I did.)it was obvious to me after watching Steve Wilson's video presentations just how knowledgeable and how good of a teacher he is.

Last but certainly not least is Sidney Eisner the "SolidCAM Professor". SolidCAM has hours and hours of free videos on their website showing just how good SolidCAM really is and what a pleasure SolidCAM is to use. SolidCAM makes better use of video to both show how their product works and to teach you how to use it than any CADCAM company I'm aware of and they do it for free!

www.solidcam.com

Jon Banquer
San Diego, CA
http://jonbanquer.wordpress.com/

[Kevin Quigley]

Is it documentaion or is it interface of the software? I would suggest that most CAD applications are easy to do basic things in once you understand the core navigation issues and building methodology (which can be handled in a 5 minute video or 20 page "Getting started" guide).

The issue is more advanced functionality.

Personally I like a printed manual I can dip into, read on the train, peruse over a coffee etc. The problem is there are few actual manuals around anymore, hence why there is a thriving independent book market.

But the big issue is that very few CAD companies think the interface through from a user's point of view all the way through the functionality in then software.

They might have a pretty interface, and make it easy to do simple tasks but as soon as you get into advanced modelling it all falls apart and you are left scratching your head and diving into the online help (which is usually less than helpful).

A lot of advanced functionality in CAD is either bought in and bolted on or added by developers who know the maths but not the workflow.

Examples of good interface/help;

Google SketchUp with the instructor active

[Dennis Jeffrey]

Documentation or courseware almost always falls short on the "How", and virtually ignores the "Why" of instruction.

I've been writing couseware for 17 years, because I was never able to find courseware that did both. I would probably been happy with the work of others if they had only considered both options, then did it right.