Documentation Discussion

I was on the phone for 90 minutes with some of the folks from SW Corp:

Mark Biasotti (product manager)

John Cochrane (product definition)

Jim Wilkinson (usability)

Dave Pancoast (training)

Greg Jankowski (customer satisfaction)

Fielder Hiss (Product Management Manager)

Donna Allman (documentation)

Except for Donna, I have met all of these folks personally, and know that they are all top-notch folks and that they know their business well. It was Mark that brought this group together specifically to address some of the issues brought up in my blog entry on Productivity and some newsgroup stuff.

This turned out to be as much a discussion between the SW parties involved as between me and them. We talked about problems and possible solutions. A meeting like this is never the end of the discussion, it is just a beginning, to make sure everyone is aware of the issue, why it is an issue, and are at least thinking about possible solutions.

The discussion started by talking about why documentation is so important. For me, the documentation makes the software more valuable, because without knowing how things work, it is useless. I also wanted to make clear that I was distinguishing between the Help documentation and the Training documentation. Training makes money for the company, and the manuals are generally well received. Training is also usually for new users, and is more intended to tell a story than to be used as reference material. They used the analogy of a camera, where users want to know how to take pictures, not necessarily what every little button does. I returned that scenario works for beginning users, but more advanced users want more detailed information, and the overview doesn’t cut it. With 600,000 users and having been on the market for 12 years, there are a lot of intermediate and advanced users out there looking for more information.

I went on to talk about SolidWorks initial philosophy when competing against Pro/E 10 years ago. We had to sell the software based on it being easy to use, in contrast to Pro/E. The documentation was simple, we didn’t use any technical CAD industry terminology, and we were trying to “dumb it down” so that it was easy to use. All these years later, the software is almost as complex as Pro/E was back then, but we are still trying to “dumb it down”. This frustrates the intermediate and advanced users. Even now with AutoCAD users being the main target and with all the SWIFT Xperts stuff, everything is aimed at dumbing it down.

The software now has a lot of more advanced functionality, which SolidWorks doesn’t have any way of describing adequately with the current corporate language. The “dumb it down” approach does not work for all users. A new approach needs to be taken. The “dumb it down” approach is what I was railing against when I wrote the SW Bible.

Then we talked about some specific examples of what was wrong with the help. I also mentioned the refreshing example of functionality which is really terrible in SolidWorks (Smart Fasteners), but my experience with the Help was actually very good because the help was straight up about the limitations of the function. This makes all the difference in the world. Instead of just perceiving the company as an inept software developer, you understand that there are limitations for reasons of specific technical difficulty.

From this discussion, several things came out:\n\n- translation cost (into 13 languages) is indeed a factor limiting the “verbosity” of the Help and the inclusion of interface images

– tech writer knowledge level of the software and common usage techniques is another limiting factor

– the speed at which everything happens in the development of the software is another limiting factor

– it’s hard and tedious work to properly index the help

Some ideas seemed to get no attention, such as the HTML based help, but other aspects of it got a lot of attention, such as searchability. Most people seem to rely on the Index more than the Search because the Search returns information which seems pretty irrelevant most of the time. SW seems to be already looking into additional search engines, and leans more toward the search than the index simply because of the difference between search technology and good old fashioned hard work.

The idea of a wiki gained some traction with some, but not with others. Using the Help as a starting point for the wiki came up, where users would comment on the help, and the comments might eventually get incorporated into the official help. Policing a wiki from the insane voodoo-based suggestions that often show up seemed to be a sticking point. The fact that SolidWorks users resort to superstition so often is a dead giveaway sign that there is not enough authoritative fact-based information available.

There was a little balking at one my top requests, which was that the Help should explain how/why stuff works or doesn’t work. They countered that this could be a never ending list. Well, it has to end somewhere, I wrote the SW Bible and essentially tried to answer those questions. It would be much more effective if the info came straight from the people who developed the functionality.

Anyway, I’ve been party to meetings of this sort before, and it’s always tough to measure the results. It does seem clear to me that the documentation department has been pretty constrained by time, money and expertise, and that it is no wonder the Help is in the situation its in. They are actively involved in improving the search, and even to make the search better than the current index. As for the level of content, I’m not sure I heard a lot of resolve to improve drastically. There was a suggestion to extend the English language side of things, and leave the other “localizations” alone. This makes sense, but I’m sure there are some folks who will have a few things to say about that. Anyone reading my blog, by definition is an English speaker, so I’m not sure that this is the best place to address that issue. Maybe Stephan Berlitz, Luc-Etienne Gagnon or Shaodun Lin would care to take something like this to another language outlet. I know that there are Spanish, Italian, German, Turkish, Russian, Finnish and Thai SolidWorks sites/forums that link to my blog, so this may find some traction through that connection.

One thing I was really hoping for was that the change would be driven conceptually by someone a little higher up. I was hoping someone like McEleney or Gopal Shenoy would take up the banner and actually drive the change. Now that both of those fellows are leaving the company, I will have to look elsewhere for a champion. All of the people involved are in charge of their own areas, but I think in order to make sure this happens, it will take someone who believes in the change to push it through and approve additional resources. I fear this will devolve into several departments with differing ideas of how change should take place, if any, and that it will stall. Without a personality leading the charge conceptually and financially, the changes may never see the light of day.

In any case, I appreciate the time that these people took out of their days to listen to my story, and any follow up work that gets done. Better documentation will mean happier users and more productive users. I hope we see some real results from this.