Monday, October 11, 2010

For the love of MSDN

I have been going through much .Net framework documentation on MSDN site lately.  I am also working on lock-picking - not any particular lock, just trying to learn a skill.
Exhausted from both those activities, and the HoustonTechFest (which was excellent), I came across a very interesting publication entitled The Document Which Used To Be Called The MIT Lockpicking Guide. In simple text with a few black and white pictures this document describes a physical object (a simple lock), it's construction, properties and behavior, and, finally, expected imperfections and analysis of their effect on properties and behavior of the lock. Then it goes on to describe a technique to pick a lock based on understanding of the lock's properties and behavior.
Thinking back to MSDN documentation with the AJAX, 6+colors color-scheme and many different icons and cryptic text, it delivers a lot less information both per square inch and per minute spent reading it. What would it take to have software documentation that shows the big picture, the particulars, the unexpected effects - in plain English, pages that load quickly, and perhaps enough colors to make the page look pleasant but no more?