In between the usual spates of frantic two-fingered typing of exciting new guidance this week, I've been attempting to expand my brain to the size of a small asteroid (with appropriate apologies to Douglas Adams fans, the size of a planet seems a rather optimistic aim). All this comes about because an increasing amount of stuff in the project I'm working on at the moment, the upcoming version of Enterprise Library, depends on new whizz-bang features of the .NET languages such as lambda expressions, nullable types, anonymous delegates, and implicit typing. As an upgraded VBScripter, much of this might as well have been written in Klingon for all the sense I could make of it.
It means I've had to do a crash course in advanced C# so that I don't look too much of an idiot at product meetings and demos by asking stupid questions such as "did you miss the word 'delegate' out there?" or "shouldn't the 'select' bit come first?". So I've been reading (and re-reading) a book by fellow Englishman Jon Skeet called "C# In Depth" (ISBN 1933988363), and I can definitely recommend it. It skips the usual "What .NET is", "How to do foreach loops", and the history of the Internet; and dives straight into the exciting new stuff in C# 2.0 and C# 3.0. It's well written and understandable to mere humans, yet delves deep into the topics and really makes sense of them. The only criticism I have is the overuse in almost every chapter of the excruciatingly awful term "syntactic sugar" when referring to the new language features.
And I've even had to order an equivalent VB.NET book as well so I can figure out how do code sample translations for the docs, and write my own demo code in both languages without just cheating and using Telerik's useful Code Converter site. It will be interesting to see if the combination of explanations from two different authors, in two different programming languages, makes the topics clearer or just more incomprehensible. Maybe after I've read them both a few times, my brain will be approaching small moon size. Perhaps I can even persuade people that my increasing bald patch is due to "syntactic squeeze" inside my head forcing out the few remaining gray hairs.
But what really prompted this week's doubtful diatribe was a throw-away comment in Jon's book. He says (though I'm not allowed to quote the actual words due to copyright restrictions) that developers previously had to rely on manually written documentation, whereas the syntax of the recent versions of languages such as C# 2.0 and 3.0, combined with the increasing capabilities of IDEs such as Visual Studio, means that this is no longer required. He suggests that documentation is often incomplete or inaccurate, and that developers rarely read it anyway.
This is kind of worrying, especially as a large part of my job is to create documentation for code projects, rather than just architectural guidance. And it seems that the bits developers do rely on most are the API reference sections that simply list and describe the classes and their members; and is built by an automated process from the generated assemblies, XML, and PDB files. OK, so this does depend to some extent on developers putting meaningful summary sections in their code for it to make much sense, but I can't see Microsoft paying me full time just to click the "Go" button in Sandcastle once a month. Do I need to start looking for a new job?
Yet, I'm not convinced that the huge amount of effort we put into producing documentation for p&p projects such as Enterprise Library is a waste of time. Yes, given a requirement to write a function to calculate some esoteric mathematical result, or interact with a Web Service, or even a whole application to do some kind of data processing, you may only need to know about the syntax and usage of elements of the language. Maybe that's what Jon was getting at. But when it comes to understanding a new technology, code library, or development framework, surely developers need some additional assistance in the form of written (or other format) guidance.
Most of the effort we put into documentation for things like Enterprise Library involves an overview of the feature so you can grasp what it does, when you should use it, and see an outline of how it works so you can understand it. Then there's information that's hard to get from looking at the code or using IntelliSense; such as configuration settings and their effects, recommendations on choosing appropriate methods and overloads, explanation of the return values and the ways you can use them, and more. I can't see how the brief descriptions in an API reference can provide this kind of assistance.
Or could it be that I'm just not a capable enough programmer to be able to do it without somebody holding my hand? Maybe I just need to get to know more people with planet-sized brains...