Jonathan Crossland
Posts: 630
Nickname: jonathanc
Registered: Feb, 2004
|
Jonathan Crossland is a software architect for Lucid Ocean Ltd
|
|
|
|
Frameworks and the MSDN Library
|
Posted: Mar 23, 2009 9:28 AM
|
|
We all know that the learning curve for Frameworks are quite high. We all know that Frameworks demand commitment, and learning time. We know this because we struggle with it everyday, whether its Java or .NET, Swing, or MFC.
1991-1993, Ralph Johnson and others wrote about Recipes and Cookbooks. There have been papers on documenting frameworks for more than 15 years. MSDN has some of the flavours but none of it is actually polished, nor tailored to the audience and the way in which people seek information.
My D4 Software Frameworks Pattern Language points you to some Patterns for documenting Frameworks:
WritingReference
You must provide a reference of interfaces.
WritingRecipe
You need to provide examples of isolated features of the framework that a pure reference cannot show.
WritingCookbook
You need to combine a large amount of recipes.
SelfDescribing
Using tools and generators, you can generate documentation.
All of them are self explanatory, except let me add, amazing that blogs seem to be the number 1 source for this kind of information, as well as google tends to find things on MSDN better than MSDN finds on their own material?.
The Solution to the MSDN Dilemna
The last one (SelfDescribing) is where I am particularly keen. Not GeneratingReference but SelfDescribing Imagine if a method on a class called MethodA() had been marked with an attribute called TemplateMethod()
Well a Tool, would be able to highlight it for you. If you had a tree of all Types, TemplateMethods and Hooks, you would now better understand the way in which the types where constructed. You would now know that MethodA() called Method(B) then MethodC(). The internals of MethodA() ois not known, shown or cared for. But from a documentation point of view it is crucual for certain designs.
It is this, that is missing from MSDN, because it is missing from all frameworks. Documentation needs to be better, but cannot, until the compiled code, can be examined in a much more thorough way. Developers of Frameworks, must declare their intentions of methods, class and patterns by attributing metadata onto it.
So the solution, is to mark the .NET Framework Types with documenting metadata. Allow all Framework developers to utilize this metadata descriptions for their frameworks, and provide a tool to inspect it.
Read: Frameworks and the MSDN Library
|
|
Previous Topic
