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

 

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.

 

For all of that, though, one of the biggest lacks I find in the help is

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

 

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

 

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.

 

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.

 

On top of that, the Help does not even indicate that you can shell a

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

 

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...

 

don't have the faintest idea.

 

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.

 

I wonder if SolidWorks knows?

 

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.