Documentation isn’t what it used to be; at least in the software industry. Twenty years ago documentation was sparse, expensive to produce and, as a result, limited to only systems that really required it.
Today we have virtually zero-cost publication channels via the INternet and collaborative web-sites provide crowd-sourced documents with hundreds of authors; in general this has been a good thing.
Last week I worked on a business intelligence system using Microsoft’s .NET platform. My experience was good using Visual Studio and C# to produce the required software very quickly. During our project there was one dissonant note; Microsoft’s online documentation contained almost no overview of the interaction between classes. Certainly I could locate class-level descriptions of properties and member functions. Every page contained a community comments section (kudos Microsoft). What was missing was a section describing how related classes interact.
More interesting was that this pattern of missing class-interaction is repeated for Apple’s developer documentation. Perhaps we’re seeing the downside of auto-generated documents; if no over-arching co-ordination class or object exists then there is nowhere to document class interactions.
So how about it Microsoft and Apple; help us out? A diagram and/or narrative description would be very useful. Help us appreciate your object models and make best use of them; provide us with some context.
Posted by robertmacgregor 
