It is an interesting process to come up to speed on LINQ and XLinq. As the programming writer who works on XLinq, I fortunately have the capacity to affect how programmers learn about XLinq.
One of my pet peeves is documentation that doesn’t teach. Too often, documentation is a mishmash of stuff aranged in a hierarchy that is oriented more towards finding out how to do a particular task. No doubt, this is useful, but it is NOT the only usage scenario for documentation, to say the least.
For the May CTP 2006 release of XLinq, the topics that I’ve been working on are those that teach XLinq.
One of the key questions when writing documentation that teaches is to identify who the reader is. Certainly, this includes the level of developer (Mort, Elvis, or Einstein). In addition, I identify very specific characteristics of my reader before writing. In the case of the XLinq docs, the reader’s characteristics are:
- Knows C# quite well.
- Knows a fair about about the .NET framework. Knows enough to lookup anything that he or she doesn’t know.
- Understands generics. This is a tough one, as generics are beyond the typical Mort programer. However, it is indisputable that an XLinq developer will need to have a handle on generics.
- Doesn’t already know about C# 3.0, including lambda expressions, local variable type inference, anonymous types, and object initializers. These topics are introduced in the docs.
Beyond that, I intended the docs to be read by developers at a wide variety of skill level. As an example, the intro to XLinq is intended to give an Einstein developer the contextual information that will help him or her to decide whether XLinq is a technology that they should investigate further. The docs can certainly be read by an Elvis developer; the high level stuff is useful, and beyond that the docs get into meaty technical detail. I am not sure if the docs as they exist will be so very useful to Morts. My question is, do Morts understand generics????
The “Learning XLinq” docs are in the XLinq Reference in the May 2006 CTP. When you open the reference CHM file, you see XLinq SDK as the top node. Under that, you will see Learning XLinq using C#, and Learning XLinq using Visual Basic. My docs are the “Learning XLinq using C#” topics. Feel free to send missives to me regarding them.