Apart 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):*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

CategoryDocumentation

- Advertising -- "why you should use this component" -- helps you find the right component.
- Thoroughly documented interface: Name and parameters of each property and method, and a description of what each does.
- A clear description (including Formal Model(s), if appropriate) of the conceptual model of the component. IE: What does it simulate? How can one best understand the overall operation of the component? Under what conditions and in what order are events fired / callbacks made?
- Cookbook / Examples
- Formal Models: "Mathematical" / UML (like StateTransitionDiagram)

The main problems I see with source as component documentation:

- Source may be unavailable with commercial components.
- Component users may not have the time to trudge through a mass of component source - they just want to evaluate and use it.
- The component may be written in another language or with another environment - so the source isn't necessarily understandable.
- The sheer volume of code is overwhelming in the case where many components are to be integrated into a product.

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):

- AbstractModelsAnswerQuestions
- Debugging
- Simulating Scenarios (the obvious CASE-tool flame-bait)

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

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

CategoryDocumentation

View edit of April 10, 2012 or FindPage with title or text search