Stirring the Documentation Pot

I thought I would do a little looking through the Help to see if it is really as bad as we are saying it is or if we are just making it all up. So I thought of something simple to look for help on. The Line tool. Nothing is more commonly used than the Line sketch entity, right? Plus it has some nifty things like infinite lines and drawing lines at an angle or with dimension that you might want to know about. Let’s have a look.

In the SolidWorks Help, click the Index tab. Now type in “line”. What do you see?

Ok, tell me, what is this talking about? This is obviously not the ubiquitous Sketch Line tool that we all use many times a day. This is talking about the LINE command used with the 2D Emulator (AutoCAD Command Line)! Looking for the most widely used tool in the software, we are instead taken directly to one of the most obscure tools in the software! This help entry doesn’t mention the 2D Emulator at all, doesn’t show the interface for the function so you know what it’s talking about, doesn’t mention that it is accessed by an add-in which is turned off by default, and most importantly the thing you’re looking for is nowhere to be found!

This is a huge embarassment for someone somewhere.

Ok, lets try again. Type in “ellipse”. Same thing. This is not just a simple mistake, this is a systematic flaw in the documentation process. In both cases, the “line” and “ellipse” commands that we are looking for are listed under “lines” and “ellipses“. The menus and toolbar tooltips clearly say “Line” and “Ellipse”. Just for reference. Not that matching the help to the actual interface matters much in Help documentation. ;op Why on earth would anyone look for “lines“?

Here’s another one. Update Custom Properties. Look in Help Index. Nothing. Look in Help Search. You will have a bit of reading to do before you discover that the exact string doesn’t exist in any of the listed entries. One more clue. Let’s say by some chance that you happen to know that this belongs to the Task Scheduler. So look up Task Scheduler in the Index. Nothing. Search? There is no entry titled for the Task Scheduler in SW Help whatsoever?!?

So you ask on the forum and figure out how to access the Task Scheduler. Now you look for Update Custom Properties in the Help Index for Task Scheduler. Lo and Behold, there it is! So you read it. Go ahead read the entire thing.

Now you know how to use the tool. But please tell me what does it do? The name of the function is too vague to tell me what I might use this tool for. The Help does not tell you what the tool does even though it gives detailed instructions on how to use it. For reference, it can add custom properties to a list or selection of files. I had to actually use the function to find out what it did.

Someone somewhere is making some bad decisions about documentation. How many of these bad examples have you come across lately?