Is it just me or …

Am I alone in finding the continual follow-the-link experience in Microsoft’s Visual C++ Help a pain in the backside?

I am trying to understand Microsoft’s Structured Exception Handling mechanism. I have found a help page entitled Structured Exception Handling. It has a few paragraphs on the subject and then a number of links at the end. These links are labelled:

  • About Structured Exception Handling
  • Using Structured Exception Handling
  • Structured Exception Handling Reference

Sounds great, doesn’t it? However, each section has its own set of links. If you follow these links you usually end up at a dead end and have to back up several clicks to resume your descent of the documentation tree.

This is web-based documentation gone mad.

What I want is to be able to print out the section of the Platform SDK that relates to Structured Exception Handling. Does that seem unreasonable?

When you are trying to understand something new, a clearly laid out exposition of the salient facts in a logical order is of importance. I do not see that here. Unfortunately, in the age of web-based help systems very little attention has been paid as to how such documentation should replace a well written manual.

Go back a few years. Ok, a lot of years. To, say, the late 80s and early 90s and you will find good manuals, on paper, with everything arranged in a logical order.

I look back to the first set of OS-9 manuals that I ever owned and, imperfect though they were, they were a solid and sound exposition of the RTOS, how it worked and how to make good use of it. I look at today’s wealth of online (and offline) HTML-based documentation systems, that I use in my day-to-day work, and find them nowhere near as good.

But then again, the late 90s and early 00s try to make reflecting on one’s work almost criminal; taking time to understand, a waste of time, … just do it.

I’d better stop now, lest burnout ensue!

Advertisements

One thought on “Is it just me or …

  1. That’s just poor documentation, in web format. I recall working with SCO Xenix, which was basically a version of Unix for 486’s, in fact Microsoft had some investment in SCO I believe. Anyway, their doc came in the form of a bunch of manuals, which I recall flipping back and forth through, that were infuriatingly vague, always referring to yet another page in another manual (so much like the doc you mention) and all but useless but to the expert Unix/C coder, who probably wouldn’t be reading them anyway.

    So lousy doc is lousy whether in web format or not. That’s why I’m always impressed by folks who figure out enough of the details to write a book or even article on some detail.

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s