Making a point without explaining the whole point of the point? *That* is the point!

by Michael S. Kaplan, published on 2008/10/09 03:01 -04:00, original URI: http://blogs.msdn.com/b/michkap/archive/2008/10/09/8992427.aspx

The alternate title of this blog: The chasm between what is done and what is said is not unlike the one between what is described and what is documented

There is kind of a subtle difference between documented and described.

For example, this Blog you are reading now? I describe things. Like when I did that 14 part A&P of Sort Keys series?

That is me describing sort keys.

Now I could have written it to be more exact, more formal, more boring, and so on.

But it still would just being description.

Because this is a personal blog of mine, not an official source of information.

I enjoy the occasional contradictions tinged with irony like when I am asked to blog about something to help get the word out there, but I myself am not hampered by consistency, so why should I require such a thing of my superiors? :-)

Anyway, the stuff I describe here might change in some future version. I doubt due to anyone just being so mean that they want to try to make me less relevant in some way, mind you -- I mean for actual business and/or technical reasons.

Now lets contrast all of this description with the actual documentation.

Like instead of that 14-part series that digs into sort keys so deep that the sort leys in question might actually feel more than a little uncomfortable were it not for the fact that they are not actuaslly alive, if you look at the LCMapString function description in the Platform SDK.

When the documentation says (and it does) that:

If the application specifies LCMAP_SORTKEY, the function stores a sort key in the buffer, as an array of byte values in the following format:

[all Unicode sort weights] 0x01 [all Diacritic weights] 0x01 [all Case weights] 0x01 [all Special weights] 0x01 0x00

Note that the sort key is null-terminated, regardless of the value of cchSrc. Even if some of the sort weights are absent from the sort key, due to the presence of one or more ignore flags in dwMapFlags, the 0x01 separators and the 0x00 terminator are still present. 

then you can count in that being the official word.

Even though it is still technically wrong (ref: A&P of Sort Keys, part 0 (aka The empty string sorts the same in every language)).

I mean, that only proves that documentation, just like description, can be mistaken sometimes.

That doesn't mean it isn't official, that you can't rely on it.

On the other hand, I think I am pretty reliable myself, in my own way. :-)

So I think everything has its purpose and I am hardly in competition with the documentation over breadth of coverage, or if I am then it wins. Though I think I can beat its pants off for depth of coverage for the topics I find interesting.

There is a great analogy I could use here but I am going to skip it since it might be taking as demeaning to the documentation and I do not want to  be judgmental about it, no matter how boring it may be at times. :-)

If you have read this far you may wonder what my point was here. I'm actually not going to tell you, because I making a point related to a topic that I can't write about at the moment, and when I say at the moment I mostly mean like ever, or for at least as long as I work for Microsoft. You can think of this blog as a way of making a valid point that everyone can now read without sharing the whole point of the point.

Perhaps at this point you are feeling a bit frustrated by all this. I know I would be.

Yet you keep reading, which I guess is nother interesting point you can bring up with whoever you like to talk through issues with like a therapist or clergyman or whatever. :-)

This post brought to you by 0 (U+0030, a.k.a. DIGIT ZERO)

John Cowan on 9 Oct 2008 10:59 AM:

Michael S. Kaplan on 9 Oct 2008 1:11 PM:

go to newer or older post, or back to index or month or day