The Zero Notebook for GEOframe components

There is the necessity to properly document the code we developed.  The state-of-art is that many Jupyter Notebooks were written to document may of the actions requested for running them. These Notebooks are made available when to sample projects are downloaded through their osf (which stands for Open Science Framework)  repository. This is probably a temporary solution which will be unified once forever in Github. However, these notebooks, see for instance the case of the Winter School  ofter are missing of an overall description which conveys all the information regarding the Component, part of which, for some component, was written in a custom LaTeX format and made available through the GEOframe blog. To make some order, I am proposing here to put the basic information in a Notebook, whose template you can find by clicking on the Figure below.

The notebook is a work-in-progress and who wants to give suggestions is welcomed. There are other two scopes for this Notebook Zero,  one is that the materials it contains can serve for a chapter in a Thesis where the component is described for its informatics and its content, with minimal modifications;  the other,  that it could be used for a possible submission of the component code to JOSS.  The latter goal would require some improvement in our GEOframe component Github site though in order to have tagged version of the software, a clean way to submit issues (a issue tracker), a set of unit test for the continuous integration of the components. We made a lot of progresses in recent years, but we are not yet there, really operational. A companion issue is where we do upload the .sim files and the data corresponding to tagged version of the components. So far they were assembled together in someone computer, compiled, eventually uploaded to Zenodo (or OSF) and made public. Streamlining the whole process in Github would be probably convenient. Going even more general, there is an installing problem of the OMS/GEOframe stuff. So far we replicated the jars (i.e. the Java executable) several times, each time we needed a a new project. It is time, I guess, to have the executable in a unique place, at Computer or User level, while the directories with data etc (so fare recognised as the OMS projects), freely replicable for different simulations, but without having to get along any time with copies of the executables.

Fair use: It is easy to make custom versions of our software components and embed it into some "proprietary platform" or "commercial" product.  We do not prohibit this use. However, it should be reminded that GPL 3.0 of the component would require a redistribution of modifications of our codes. 

Besides, even its use would require a note, somewhat visible that makes clear the product is powered by GEOframe. So we expect that fair use of our software in some enterprise would be acknowledged by: "Powered by GEOframe and OMS3".

No Communication, No Science

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:

• The Developer's template
• The Linkers Template
• The Users  (MS) Template 
• The Users (Run) Template 

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.