Help File Coverage; 95%, 99% or?

In the discussion of Display States several notes on the Help file results were made by Ed Eaton who noted:
"HELP is not as explicit as I would like (for starters, there isn't
even a 'display states' item in the index - what there is can be found under 'display pane')."
I personally have searched for major features, only to find similar results occassionally...meaning no result. It is extremely frustrating when you search for a specific word you know describes something in SolidWorks and get a non-result.
Am I alone, or do other SolidWorks users (read funders of SolidWorks payrolls) think SolidWorks is skimping on the technical writing & checking for the Help file (including maintaining a content check database to make sure each feature & option is covered)?
Later - Bo
Add pictures here
<% if( /^image/.test(type) ){ %>
<% } %>
<%-name%>
Add image file
Upload
I've done a fair amount of research lately in the Help files, and also in the Customer Portal.
The writing of the help files has been contracted out. This is not necessarily a bad thing, after all I make my living doing work that is contracted out. I suspect that the folks who wrote the help did not have much inside access to SW Corp technical expertise, and that there was not a lot of oversight of the finished product. In many cases, the help materials are incomplete, as you have pointed out, and in a few cases, even incorrect. The biggest thing I notice about the help in the last 2-3 releases is that it looks to have been written in a big hurry. There is very little elaboration on topics that really require it. Granted, writing the SolidWorks Help document is an *immense* task, and probably the equivalent of a few hundred printed pages.
Help would be more helpful if it were written by a user instead of by a technical writer. That's obviously just an opinion, but polished sentence structure does not help me understand.
The Help tends to tell you what buttons to push, but not why you push the buttons. Help is more about interface than functionality. Interface should be a no brainer. You should be able to understand the interface just by looking at it (although we all know it doesn't really work this way in SW). I want the Help to help me understand mainly what sorts of results I can expect, and maybe some secondary hints about using the interface.
For all of that, though, one of the biggest lacks I find in the help is screenshots of the interface. Many times the word description assumes you access a command either through the menus or the toolbars or the RMB menu. Really, a picture is worth a thousand words. Really.
Every year since 2001 I have done a detailed summary of the Tools Options settings, and I usually have to note a few things for which the help is either wrong or misleading. One thing that surprises me in a positive way is how little outdated information you find in the help. As fast as the software changes, you find very little obsolete data. Sometimes you will come across terminology which is obsolete, but has seemed to stick like "base feature", "base part", "derived part". Old hacks know what these are, but the terminology and in some cases concepts are missing from the new software.
One area of the software that seems well documented in help is configurations. I was able to find a lot of detail on design tables and what is and isn't configurable. There were some omissions on really detailed and possibly obscure topics, but I thought it was well done. Of course, some one will come along and disagree. On the other hand, the info on Library Features was scant, and on Toolbox non-existent. They didn't even try.
Some topics such as Smart Fasteners actually go to the extent to tell you situations under which you shouldn't expect something to work, but I think this one function is soooo bad they had to say something about it, and a self-critical view is clearly not the norm for SolidWorks.
Sometimes you get different results in Search which you don't see in the Index. I've run into topics that are not listed in the Index at all, and can only be found by going one by one through the Search results. I find the Search side of it very difficult to get useful information from, so I usually stick with Index unless I run into a wall. The Contents tab is useless. I hate huge non-alphabetized lists of general data.
I used to always send in problems I found in the documentation, but there are so many problems, and frankly, it doesn't pay very well. I wish I kept a list of everything just for my own purposes, because I never remember all of the details.
I think it would be useful if the tutorials were integrated into the Help. There are several nice little tutorials that I had completely forgotten about.
I do see that they took one of my crticisms to heart and replaced the "vertical market design tools" with "industry-specific design tools". There is little more annoying than marketing jargon in technical documents.
Depending on what you are looking for, the Customer Portal may be the place to look. The interface for it scores in the lower 60% range, but the content is in many cases very good. You may have to wade through some obsolete entries and off-topic items that are not clearly marked (such as an obscure Cosmos function being discussed with no indication that it is a Cosmos function - leaves you scratching your head), but to me its worth it because you can find truly useful information here. This is where SW talks about reality. This is where the tech support guys talk. No polished grammar (in fact, they don't seem to be proof-read at all), but you can read about SPRs and limitations, which you don't find in the Help. So much of the supposed problems you read here on the NG are superstition, poor description and observation, not verified or verifiable. Customer portal is immune from that junk because the SW tech guys (not resellers) write it. I give those guys some credit for knowing stuff. They might not be so good with various applications of the tools or sometimes you can catch them on an obscure function, but they know the hell out of most of the stuff.
Add pictures here
<% if( /^image/.test(type) ){ %>
<% } %>
<%-name%>
Add image file
Upload
The help files in my opinion have become less detailed with each new release. Your observations are valid, so now what? The management at SolidWorks is not focused on a quality product. They talk about the product being driven by their customers, but their actions speak louder. I frankly don't believe they have the leadership or focus within the organization to resolve all the deficiencies.
I followed Ed's piece on Display States. I couldn't agree more, the documentation is terribly lacking. I too would like to see them add more illustrations, explanations and examples to compliment the one-two-three step command instructions. Sounds like an opportunity for someone to write a book: SolidWorks Help for Dummies as an add-on.
The task of writing the help files would have been much easier to maintain had someone been constantly working to improve and update the existing data base. Anyone up for the challenge of establishing a beta test program for SW Help Files :-(
Kman

Add pictures here
<% if( /^image/.test(type) ){ %>
<% } %>
<%-name%>
Add image file
Upload

I have spend considerable time "looking" for some button that is described in the help file.. :-(
An idea that I have tried to promote is the implementation of a series of training videos. If they were fairly short but a large number of them then it would be easy to search for them with through help. Currently some VAR's have made some efforts for this, (without a search ability) but the cost per seat is fairly high. If SW would do this instead of the VARs the cost could be as low as $1 per seat.
Ed
Add pictures here
<% if( /^image/.test(type) ){ %>
<% } %>
<%-name%>
Add image file
Upload
Ed, you noted "If SW would do this instead of the VARs the cost could be as low as $1 per seat."
My bet is if SolidWorks improved the Help system, that the cost would not be that high for SWks, actually, and indeed what it would do would reduce the load on the end users AND the VARs, because they would get less phone support calls (at least from me they would, though I don't call a lot).
Better Help files are strictly a Win-Win-Win for SolidWorks, VARS, and Users by everything I know from using CAD 20 years.
My experience with a handful of CAD applications in both 2D & 3D is that the Help &/or "Book" manual for the end user ALWAYS lags in providing key new COMPLETE information. It always seems to me like TRAINING ISSUES TAKE A BACK SEAT from the software team and their management.
If I ran a software team, I would have the "Help System, Tutorial, Manual" tech. writer/s sitting right with the software team, continually revising and checking the 'manual' to keep it up to date, where the writers themselves verify and can ask questions easily of the programmers and interface designers.
Bo
Ed wrote:

Add pictures here
<% if( /^image/.test(type) ){ %>
<% } %>
<%-name%>
Add image file
Upload
Here's a great example of the Help covering the button pushes, but overlooking more important stuff. This is just one among many, the latest I have come across:
SolidWorks Task Scheduler help, Update Custom Properties topic. Access it through the Help button on the Update Custom Properties dialog in the Task Scheduler.
It tells you in detail how to set up the scheduler and how to get the task to run, but it never explains what the function actually does. This is the most infuriating type of help oversight. The person who wrote the help obviously knows this function well, but it is not at all clear what it does. What are the results that you can expect? Yes, I know you press THAT button, but WHY? This is the problem with tutorial based instruction. Tutorials are linear in nature even when the output possibilities are not.
Add pictures here
<% if( /^image/.test(type) ){ %>
<% } %>
<%-name%>
Add image file
Upload
Yes I've wondered what that button does, my short experience with the task scheduler was frustrating and short lived, I went back to using PAC4SWX.
I'll probably experiment with the Task Scheduler again in SolidWorks 2007, when I install 2007 that is.
The time to install SolidWorks 2007 will be when:- a: I feel the need to waste some time b: I don't have enough stress in my life and feel I need some more. c: My clients aren't serious about those impossible deadlines. d: When the whining in the newsgroup has reduced to low level (ok this one is just a fantasy) e: After drinking heavily
John Layne www.solidengineering.co.nz

Add pictures here
<% if( /^image/.test(type) ){ %>
<% } %>
<%-name%>
Add image file
Upload
Forgot to add d: when sufficient dust has accumulated on the Upgrade cardboard box.
John Layne
message

Add pictures here
<% if( /^image/.test(type) ){ %>
<% } %>
<%-name%>
Add image file
Upload
Or, you receive a formal notice from SolidWorks that the next release is just around the corner.
Kman

Add pictures here
<% if( /^image/.test(type) ){ %>
<% } %>
<%-name%>
Add image file
Upload

Perhaps theSWx Help menu should be modified to suggest 'drinking heavily' as a way to optimise the use of the software? :) I anticiapte the day that Joe Dunne and/or Aaron Kelley uses that kernel of wisdom in a product presentation. It IS a tried and true technique...
Add pictures here
<% if( /^image/.test(type) ){ %>
<% } %>
<%-name%>
Add image file
Upload

On a more serious note, what does it actually do?
John Layne www.solidengineering.co.nz
Add pictures here
<% if( /^image/.test(type) ){ %>
<% } %>
<%-name%>
Add image file
Upload

don't have the faintest idea.
Add pictures here
<% if( /^image/.test(type) ){ %>
<% } %>
<%-name%>
Add image file
Upload
I wonder if SolidWorks knows?

Add pictures here
<% if( /^image/.test(type) ){ %>
<% } %>
<%-name%>
Add image file
Upload
John Layne wrote:

A little curiosity pays off. If you just decide whatever it does, that's what I'm going to do, you come to an interface that allows you to enter property names, types, values and even configs to assign the values to. In this dialog it says "Please specify the custom properties to add or modify". Earlier you had to select a bunch of files or folders to do the mystery operation to. If the help had shown an image of the interface, that would have offered a clue about what the function does.
So maybe "update properties" is the wrong name. It should be "mass populate properties".
This is cool functionality, now that I see it. People ask for this frequently.
Think of all of the extra functionality that could be added to SolidWorks simply by documenting the fact that it exists! That's free development time.
Add pictures here
<% if( /^image/.test(type) ){ %>
<% } %>
<%-name%>
Add image file
Upload

Maybe I should have at least opened the Task Scheduler and had I look, sorry for being a lazy SOB and making you do all the work.
Interesting -- After a quick look I'll stick to using Propa-Gator which I paid for a year or 2 back, after consulting this group.
Propa-Gator has a number of advantages like:
1/ being able to overwrite configuration specific properties without know the configuration name beforehand. 2/ having the choice of overwriting or not overwriting a property if it already exists. 3/ the ability to search, replace or delete Property Name or the Property Value. 4/ The Add Files window allows the user to more easily select more than one file i.e. using CTRL and Shift to select the files. (The Add Folders functionality is the same as the Task Manager)
The really ironic thing is, the Help file with Propa-Gator doesn't work properly. I haven't used the Help in a while but I remember having go into the program directory and manually open the .chm file. The lack of working Help file really P----- me off at the time, I did correspond with the programmer - but a year or so later it still seems the same. I had a lot of motivation at the time to understand Propa-Gator, either that or alter several hundred properties manually.
John Layne www.solidengineering.co.nz
Add pictures here
<% if( /^image/.test(type) ){ %>
<% } %>
<%-name%>
Add image file
Upload

I do think that the technical writing could use a lot of attention and have made the case to SolidWorks many times through every avenue I have.
Just one sample: One time I found myself out to dinner with one of the guys who writes the help, and I took the opportunity to make the following case to him (tactless, yes, but I was there so I took it):
Shell - the sample in the help (and as I recall, the tutorial) shows picking a single face to shell a model. Way back at my old job, I and many of my coworkers had no idea that you could pick multiple faces for a shell. When I read about it on the newsgroup it was a revelation for all of us. I suggested to Mr.Help-man that if he was going to put forth a simple sample that he try to show a more elaborate use of the function (shell a model by picking two faces) Granted, there is text (now?) saying you can pick more than one face, but it is human nature to skim - if you are going to invest in a sample, make the images suggest as many of the possibilities as practical.
On top of that, the Help does not even indicate that you can shell a model by picking NO faces. That's a pretty significant omission that still exists in the help for 2007. That's a shame.
On the flip-side, to be fair (oh man, here's why the posts get long), there is some pretty good stuff included in the 2007 shell Help that has Mark Biasottis fingerprints all over it. The help now gives suggestions on how to overcome shell errors - it isn't formatted well imo, but its there. Thanks Mark.
While on a rif about shell, there are a few mysterious items in the shell help about 'Find' and 'Modify'. I gave up after about a minute trying to figure out what the heck they were about. Why are they useful to me? How the f*** do I access them? No indication that I could see.
____________________________________________
My major 'Help' beefs: 1)    There should not be any term used commonly in SWx (like display states - a convenient sample) that is not in the Help 2)    Every term used in error messages ought to be in the Help. "Feature failed due to geometric inconsistency"? Search for 'geometric inconsistency' - nothing. "Cannot cap the side sheets"? Search for 'cap' or 'side sheets' - nothing. We need help most when something fails - help us 3)    Rework the help interface - frankly, I hate that when I enter 'Shells' in the index that a separate window pops up with a list of stuff that I then have to click though - I find it hard to keep track of what I have read. If they have to do it that way, at least follow the google example and change the color of things you have already read. I usually find myself clicking the same dead end a few times. In the Index, if I enter Shells, the shell feature is the ninth item that comes up - who has time for that? 4)    If there is a function described in the Help, for crying out loud, tell me explicitly how to get to it. (or to Matts point, show me with a picture. Thanks matt for a number of really good observations) 5)    Give me a button (pin?) that allows me to keep the Help on top of SWx when I go to SWx trying to follow its instructions (didn't there used to be one? Is there one that I am now missing?) ___________________________________________________________
Final, potentially counterproductive stab at fairness (damn these personal ethics I have) - the SWx Help does need a lot of Help, but it is dramatically better than the Office help - powerpoint, word, and excel have the absolutely least 'helpful' help I have ever seen. Please, Swx, don't use them as your benchmark. You can do better.
Ed Eaton
Private to BO - dude, I am so glad about the threads you have been starting in the last month or so. They have been interesting and engaging, and I honor the class you have. Thank you.
Add pictures here
<% if( /^image/.test(type) ){ %>
<% } %>
<%-name%>
Add image file
Upload
Didn't know that, thanks Kman

Add pictures here
<% if( /^image/.test(type) ){ %>
<% } %>
<%-name%>
Add image file
Upload

Kman wrote:

And THAT'S why I am a fan of this NG. Not my discovery (sorry I can't credit the orignal poster, it was forever ago that it came up). But I'm happy that passing it along might be of some use. Just pick the body Ed
Add pictures here
<% if( /^image/.test(type) ){ %>
<% } %>
<%-name%>
Add image file
Upload
In the past it was possible to search through the SW Knowledge Base for important details. I don't believe I have used what used to be the knowledge base for some time. It has been culled and buried in the subscription area. The KB simply couldn't keep up with the change within SolidWorks although it was generally written by more knowledgeable and informed individuals that the help sometimes is. This is one of the problems we all face. What was proven behavior last year might be obsolete or just plain wrong this year. To use the KB of the past required reading all the articles and then trying to coalesce that information into a definitirve behavior.
It isn't just the general help, but the API help is sometimes very skimpy on important information. Frequently help is given in the form of example, which while not necessarily a bad thing, doesn't really always give a clear definition of what is going with an object, method or property.
Add to the forgoing the frequent practice of defining what is proper behavior by using the most current release and service pack as a bench mark or by having to systematically test the software to figure out what is going on certainly leads to a lack of usefullness and is definitely a major performance hit. It would seem that a clear reference that didn't change but rather defined the ideal behavior of the software would be a boon to both the user and to SW in achieving what the user's desire from the software.
Of course a clear reference would make it harder to compete in feature wars with Inventor, SolidEdge and the like because the developers wouldn't be able to follow the latest fad like a drunken sailor on shore leave. It would also leave SW open to cloning just like ACAD was cloned via the standardized dxf/dwg file. Thus users are required to weave and bob through "improvements" to the interface and are assumed to be quicker on the uptake than the competition is.
Add pictures here
<% if( /^image/.test(type) ){ %>
<% } %>
<%-name%>
Add image file
Upload

Polytechforum.com is a website by engineers for engineers. It is not affiliated with any of manufacturers or vendors discussed here. All logos and trade names are the property of their respective owners.