I’m at Microsoft Tech-Ed in Berlin where 7000-odd IT admins and developers (though more admins) are looking at Microsoft technology.

I was browsing round the stands in the Technical Learning Centre here when I came to one where the technical documentation team at Microsoft was handing out a survey. Fill in the survey, get a plastic rocket. I looked through the survey where you had to rate innumerable aspects of the documentation on Microsoft’s technical resource sites (MDSN, TechNet etc).

I refused to complete it, on the grounds that it would not yield anything of value. I can put numbers in boxes as well as anyone else, but they tend to be arbitrary, and all too often the real answers cannot be easily condensed into a 1 to 5 rating. I said that the way to find out what people thought of the documentation was to ask them, not to get them putting numbers on a form.

Inevitably, the guys asked me that question, and we has a discussion of the issues I’ve found with the sites including:

• Broken links. I don’t think Microsoft should ever delete a knowledgebase entry. Mark them obsolete or even wrong, but don’t remove them.
• Too many locations with overlapping content – MSDN, Technet, specialist sites, team blogs etc.
• Documentation that states the obvious – eg how to enable or disable a feature – but neglects to mention the interesting stuff like why you would want to enable or disable it and what the implications are.
• Documentation that is excessively verbose or makes you drill down into link after link before finding the real content.
• Documentation that is not clearly dated, so that you might be reading obsolete advice.

Anyway, I felt I had a worthwhile discussion and was listened to; whereas completing the survey would not have brought out these points effectively.