This is a first trial to produce some standard templates for documenting our modeling work. It starts from the idea that we use a component-based environment (
OMS) and there are at least three types of actors that can use (or help to produce) our software:
- Developers: these are those who develops the components. What they need to know is the overall scope of the component, its design, its classes, the algorithms it uses and some reference to check it all.
- Linkers: these are those who uses the components to create modelling solutions (MS). Their work is made before run-time by means of a scripting language (in our case based on Groovy). In our case they produce a .sim file that allows the execution of the model inside the OMS3 console. They need also to have information about the IO data each component require and they could not be necessarily know the internals of each component, like the cook do not need to know how the cooker internals are made (they call it encapsulation of information, and information hiding, which has a positive connotation in object oriented modeling)
- Users : They just run MS, but they should also provide information about their run. So one of the template can be used for documenting single runs of MS, specifying the inputs and the setup of the numerical experiment.
Thus, we actually delineated four types of documentation (for internals, for externals of each component, for their compositions, and for specific runs) which we can solve with four templates. They are produced in LaTeX and are still experimental:
One could observe that actually these four types of documentation can should be produced at different stages of the component's production.
The Developer documentation should be produced while designing the component, and, potentially, before the component is produces. Its structure can greatly help the design, and avoid the production of software without design. The Linkers' documentation should be produced just after the production of the component, while the component is tested. The Users documentation which presente assembly (composition) of components during experiments setup, or, if of the fourth type, before (in contemporary) a run is sent. This implies a little discipline but it would help a lot to save personal and collective time. Besides, it would be easy then to obey to the requirement of making replicable research.
All of this is work in progress and will be improved during the effective use of the templates. Suggestions are welcomed.
Saying this is to produce components documentation, we still are missing an appropriate type of documentation for Application, like, for instance the OMS console. For this type of documentation, we also have a template, copied from the
uDig walktroughs. An example, also in
LaTeX, can be found
here.
