Component Documentation
Component DocumentationApart from the CatalysisMethodology and use of OpenSource, does anyone know of a different approach to component documentation?
What sort of documentation would people need to be able to download, evaluate and use a component from an intranet repository for example? (Among other things if you don't have source, you'd need some documentation to elaborate on the AbstractInteractions that take place between components.)
The main problems I see with source as component documentation:
The ideal component documentation would be mathematical models, at some useful level of abstraction, of the interaction protocols used between components and the behaviour of concrete components themselves. Some research groups are using CSP or labelled transition systems for this kind of modelling. --NatPryce
I doubt this is ideal. It takes a long time to figure out how to use a mathematical model. How many programmers read the denotational semantics of a programming language when they want to understand it? A mathematical model is good as the ultimate specification of a standard, but we need something simpler for people who just want to learn how to use a component (or any complex system). Mathematical models are especially bad when you are looking for a component that might meet your needs. You want to spend just a few minutes reading a description to see if it is what you want, and mathematical models will take too long to understand.
In my opinion, we need several levels of documentation. First, you need advertising that explains why you should use the component, gives the context for using it (other components that are needed) and some examples of what it should do. You should be able to read this quickly.
Second, you need a cookbook that tells you how to use the component. People always want examples at this time. But they also like short, problem-oriented instructions. I think patterns can work for this kind of documentation. See DocumentingFrameworksWithPatterns.
Third, you need a precise specification that can answer all your questions about the component. A mathematical model could work for this, as can the source code.
In general, people use the first kind of documentation to figure out whether they want to use the component, the second to use it the first or second time, and the third only if they run into problems (but haven't given up) or have used it the component a few times and want to do something more advanced with it. -RalphJohnson
Don't get me wrong, I certainly see the point of the "advertising" documentation for "auditioning" components. If you think a formal model of a 3 colour traffic light widget is absurd wait until you've sat through three slides of equations that show a toggle switch being flipped. I'm not making this up(!)
Possible uses for a formal methods based documention (IMHO):
A lot of the formal methods work seems to be concentrated on proof for safety critical systems. Documentation for most component-based environments will almost certainly require a different emphasis.
I'm not against the lightweight "advert" style documentation per se, it's just that I'd like more information to fall back on when things get complicated.
What about some sort of Dewey Decimal system for classifying components. The "advert" could specify a class mark that gives a rough idea of the placement of the component in "library space".
Doesn't OMG's "Common Facilities" attempt to do something like this?
Actually, I agree with Ralph also...
If you need to analyse exactly what a component does, and certain properties of a system composed from components, then a formal spec that can be mechanically checked is, IMHO, what you need.
However, if you want to learn how to use a component, then a tutorial followed by patterns is probably the best form of documentation. I have been very impressed by the Java tutorial.
--NatPryce.
Big problem I often have with VisualBasic/ActiveX components is that the only documentation is (1) a list of properties & methods with short descriptions (not much better than what's in the TypeLibrary?, and (2) example programs. Given a complex control, like VsFlexGrid?, one desperately needs to know what events (callbacks) fire, under what circumstances, in what order -- and what properies are available / valid at each point in the process. As far as I can determine, there is no such documentation available. -- JeffGrigg
EditText of this page
(last edited April 10, 2012)
or FindPage with title or text search