One of my favorite softies, Eric Fleischman, is doing some S.DS.P programming these days.  He demonstrates a useful technique, which is how to do WKGUID searches to find well-known objects in AD or ADAM.  For those not familiar with this, AD and ADAM have a set of "well-known" objects that the directory always contains and applications may need to find to do reasonable things.  However, the names of these objects may be internationalized, so it may not be possible to find them by name across different implementations of the directory.  By referencing them by the "well-known" GUID, a published value, you can always find them.

One of the things we didn't do in our book was provide matching S.DS.P samples for most of the techniques.  In fact, we barely covered it at all.  I still have some regrets about this, although I also think we probably did the right thing.  If the book had been 800 pages due to all the extra samples, that would have been tough.  I do think there might be a place to supplement the material with online materials at some point.  I'm not sure another print tome dedicated to the subject would ever sell very well as the audience is probably limited and likely needs the material less than than the audience we originally wrote the book for (I could be wrong about this).  The internal debate continues...

One of the things that Eric does hit on is the somewhat sad state of affairs of the MSDN DS API documentation.  The S.DS.P docs are especially heinous, as they include almost NO samples and even have some stuff documented as wrong or misleading.  For example, the documentation for the DistinguishedName property on the SearchRequest class doesn't even succeed in identifying that as the search BASE of the search, instead calling it the "object to search for".  If it wasn't for the fact that there is no other obvious choice, an experienced LDAP programmer might not even understand what it is doing!

Additionally, the SDK docs for the directories themselves (AD and ADAM) are still mostly written for the unmanaged VB or C++ programmers with little attention to the managed code devs (although ADAM is much better about that).  However, you won't find a single S.DS.P sample in any of that.  It is as if the API didn't exist.  The managed code docs are also spread out between the .NET SDK and the Directory Services SDK, so it is hard to know where to look to get help.

There are two things missing here. 

• The S.DS.P docs are just embarassing and must be improved.  I'll give it some more time. 
• The overall DS API documentation lacks strategy and makes the platform harder to consume than it needs to be.  Sure, that helps drive sales of our book, but trust me, we didn't write it to make money.

On the bright side, there is a lot of low hanging fruit available here. :)