It looks like my last post on documentation (or the lack thereof) has gathered some feedback (Hello Rigel :) so I just wanted to clarify a few points. Firstly, having previously edited books on programming, I find it very hard to read any technical material without a highly critical eye. I find myself getting frustrated when I see simple mistakes, shortcuts, and general sloppiness in articles. I experience similar pain in my day job when I encounter documentation written by others, and often have to stop myself from grabbing that documentation and helping to fix it when I'm supposed to be working on other things. The point is that many people (ok, most people) view documentation as a chore, something to be done at the end of a project because it's on the project planner. I've seen many project plans with developers and infrastructure people alike being allocated to develop a solution over a period of months, and allocating little over a day or two to "documentation". That's not what it's all about, people.
Documentation is not supposed to be "because we have to". It's because you _need_ to. If you've spent the last couple of months developing a system, whether it's completely bespoke, or whether it's extending / adapting an existing solution, your approach needs to be written down so that some poor sod who comes to look at it a year or two down the line can get some level of insight into what was going on in your head at the time. I spent about four months on just such a system a few years ago, which was a highly-customised implementation of Microsoft Content Management Server 2002. I'm glad I took the approach that I did and dug in my heels when it came to documentation, because if I hadn't, even I would have trouble, looking back at the project three years later, understanding what it was that we did and why we did it that way. That particular project is a good example of a need for documentation - in the three years since it was rolled out, all the other developers, the project manager, even the original sales account manager have all left, and the only people who have any knowledge of the system at all are the system tester (who isn't a developer), and myself (and I just took over a year out of work for maternity leave).
Now, that was a relatively small project - four developers, four months. In my last post, I talked about Community Server and Microsoft Office SharePoint Server 2007. Community Server is a much bigger project than the one I worked on, and the guys have produced a book to help developers hoping to customise their product. Don't get me wrong, this is great stuff, and I'm glad they've done it (though I've not yet read the book, so I can express no opinions on the content of the book yet), since this means that they have documented their product in a way that is accessible to developers. They have done a great job on documenting the product for end users, by the way - Rob Howard himself does a lightning fast tour of the product over two video streams that gave me all the information I needed to decide that it was a good fit for the solution I have in mind. I guess I was just a bit disappointed with the quantity and quality of information available via the wiki. It's important to have basic documentation available and accessible to people wanting to use your product, and that's something that can be time consuming and difficult to produce without having access to a dedicated team of people who are able to build this sort of thing alongside the product.
Microsoft, to their credit, are so much better at this than they used to be. Back when .NET first arrived, the quality and quantity of information in the .NET SDK, for example, made the editors at Wrox have to really stop and think about how to approach the book market. The SharePoint SDK (my current companion), is fairly thorough, but I am finding myself getting a bit frustrated with the quality of some of the walkthroughs (notably, the Workflow walkthough). For starters, anyone who leaves anything with the glorious Visual Studio autogenerated title of thing1 (whether it be textbox1, task1, or workflow1) should have their wrists slapped hard. I've had to debug and fix code written by people who never bothered to rename their controls on an ASP.NET page, and it doesn't take long to get really fed up with trying to figure out what label15 is referring to, or wonder why someone would ever be happy checking in code featuring textbox1, textbox2, and so on. Perhaps I should log that as a request to the VS team for the next edition of VS (though I'm probably too late for VS2008) - please, whenever anyone adds any control to any page / form / workflow / etc., force them to name that control! Anyway, I could go on (and would, if I didn't have other stuff to do), so I'll have to stop here. Maybe some day I'll put together the DSG guide to writing successful documentation!