| 4 | | The current documentation of ORCHIDEE is incomplete, inconsistent in its level of detail, tri-lingual, fragmented and has been published in black, grey and white literature. Although considerable work has been done in the past, it is difficult for the current users to benefit from this work. The current organisation of the documentation is unlikely to attract new ORCHIDEE users and it is unlikely to meet any traceability or reproducibility standards required by modern science. |
| | 5 | The current documentation of ORCHIDEE is incomplete, inconsistent in its level of detail, tri-lingual, fragmented and has been published in black, grey and white literature. Although considerable work has been done in the past, it is difficult for the current users to benefit from this work. The current organisation of the documentation is unlikely to attract new ORCHIDEE users and it is unlikely to meet traceability standards required by modern science.[[BR]] |
| 9 | | == Guiding principles (2/2011 |
| 10 | | 1. The user should be able to follow (by means of hyper-links) the computational chain from forcing to history file or the other way around. |
| 11 | | 1. The documentation should be dynamic in that it is integrated into the svn system. Documentation and executables are compiled at the same time. The documentation reflects the version of the code that has been compiled. |
| 12 | | 1. The documentation needs to serve multiple-purposes i.e. it is the basic information for beginners to get started but it should have additional functionality such that advanced ORCHIDEE users can use it as an analytical tool to understand model results. |
| 13 | | 1. Special attention should be paid to flags that determine the modelling sequence, such flags should be documented and become searchable. |
| 14 | | 1. The functionality of the documentation should work even when the documentation is incomplete. This gives time to improve and complete the content over time. |
| | 10 | == Guiding principles (2/2011, 02/12/2011) == |
| | 11 | 1. The documentation serves multiple-purposes i.e. it is the basic information for beginners to get started but it should have additional functionality such that advanced ORCHIDEE users can use it as an analytical tool to understand model results. |
| | 12 | 1. The documentation will be dynamic in that it is integrated into the svn system. Documentation and executables are compiled at the same time. The documentation reflects the version of the code that has been compiled. |
| | 13 | 1. Ideally, users should be able to follow (by means of hyper-links) the computational chain from forcing to history file or the other way around. |
| | 14 | 1. Flags that determine the modelling sequence, should be documented and should become searchable. |
| | 15 | 1. Tier 1, tier 2 and tier 3 documentation are foreseen. Tier 1 consists of the documented source code, tier 2 uses basic dOxygen commands to extract basic information from the source code and regroups it in an html and pdf document. Tier 2 documentation foolows the sequential structure of the source code itself. Finally tier 3 uses advanced custom-made dOxygen commands that support compiling a process-based logic i.e. how is LAI calculated and updated throughout the code? |
| | 17 | == Examples and protocol (01/12/2011) == |
| | 18 | A preratory meeting clarifying the documentation effort was organized on December 1st 2011. The presentation given at the meeting, the agreed workplan and protocol can be downloaded below. |
| | 19 | |
| | 20 | 1. Aims, concept and planning of the documentation effort and retreat [attachment:1-Retreat_intro_111201.ppt] |
| | 21 | 1. Annotated example to help the responsibles in preparing documentation [attachment:2-ScientificDocumentation_111201_Part1.pdf], [attachment:2-ScientificDocumentation_111201_Part2.pdf] and * [attachment:2-ScientificDocumentation_111201_Part3.pdf] |
| | 22 | 1. Who does what? [attachment:4-Retreat_Workload_111201.doc] |
| | 23 | 1. A protocol and two examples were prepared to guide the documentation effort. All can be downloaded below. Alternatively, the examples or can be retrieved from the documentation branch which is readable for everybody (and writable to the administrators). Use the source code from this branch (1.9.5.2) as your starting poit (to avoid documenting old code). |
| | 24 | Protocol for documenting source code [attachment:3-Protocol_111201.doc] |
| | 25 | Stomate_alloc.f90 [attachment:stomate_alloc.f90] |
| | 26 | Diffuco_trans_co2.f90 |
| | 27 | |
| | 28 | Updates to be expected between 01/12/2011 and 19-20/01/2012 |
| | 29 | * Technical: Template for a Module Header (F.M.). |
| | 30 | * Technical: Create a LaTeX file that groups all variables names/symbols used in equations in order to harmonize. If available, add the corresponding CMIP5 name, see [http://forge.ipsl.jussieu.fr/igcmg/wiki/IPSLCM5A/Sorties/EquivalenceIPSLCMIP5]. |
| | 31 | * Organization: Plan a second meeting early in January to ensure the preparation stays on track. (F.M.) |
| | 32 | |
| | 33 | [[BR]] |
| | 34 | == THE JANUARY 2012 RETREAT == |
| | 35 | When going to the retreat > 90% of the work should be done. This implies that at the start of the retreat the draft version of Tier 1 documentation is available. |
| | 36 | |
| | 37 | During the retreat we aim for: |
| | 38 | * Consultancy with N. Viovy, N. de Noblet, A. Ducharne & Jan Polcher (by phone) to check and clarify hard bits (the remaining <10% that was not prepared before the retreat)) |
| | 39 | * Documenting overlooked subroutines (Tier 1) |
| | 40 | * Reviewing each others documentation (Tier 1) |
| | 41 | * Compiling Tier 2 documentation (Tier 2) |
| | 42 | * Adding internal hyperlinks for in and output variables (Tier 3) |
| | 43 | |
| | 44 | * Organization: Check if attendees need a 'Mission Order'. |
| | 45 | * Organization: Constitute a Review Committee including possibly P. Ciais, G. Krinner, S. Piao, ... (S.L./M.M./P.P.) |
| | 46 | * Communication: A report will be presented at the end of the retreat to some VIPs (IPSL, LSCE, LMD). (P.P.) |
| | 47 | [[BR]] |
| | 48 | |
| | 49 | ==TECHNICAL ASPECTS == |
| 48 | | |
| 49 | | An Open Office plugin ([http://writer2latex.sourceforge.net/index.html writer2latex]) |
| 50 | | is available to convert all type of Open Office files to Latex. |
| 51 | | Hence, existing documents can be easily transformed. |
| 52 | | |
| 53 | | == Demonstration (9/2011) == |
| 54 | | Fabienne will use existing and new functionalities of Doxygen to merge existing |
| 55 | | documentation with the phenology module. This will be a first example where attention |
| 56 | | will be paid to the content and appearance of the documentation. An initial set of |
| 57 | | rules has been defined but this set will most likely change following the experiences |
| 58 | | of Fabienne.[[BR]] |
| 59 | | 1. Document the smallest possible units i.e. a line of code or a couple of lines. |
| 60 | | This approach ensures that following an initial effort it is a lot easier to keep |
| 61 | | the documentation up to date as there is a clear relationship between the |
| 62 | | documentation and the code. |
| 63 | | 1. Have a scientific description at the start of the code. Avoid lengthy blocks of |
| 64 | | text because this is hard to maintain and will most likely get outdated pretty fast. |
| 65 | | It can also hamper readability of the code. |
| 66 | | 1. Give full references of the scientific literature used in support of the code. |
| 67 | | 1. Add flow charts to explain the structure of the (nested) if-then-else. |
| 68 | | 1. Each variable/parameter has a standardized description containing the following |
| 69 | | fields: Variable name, !Local/Global, Dimensions, units. |
| 118 | | == Future activities == |
| 119 | | 1. Present demonstration project at a reunion suivi (Fabienne & Martial) |
| 120 | | 1. Refine documentation protocol (Sebastiaan, Fabienne & Martial) |
| 121 | | 1. Develop additional functionality if essential for tier 1 documentation (Martial) |
| 122 | | 1. Organise documentation retreat (12/2011?) |
| 123 | | 1. We have to define standard header for all documented module. Martial has listed some header [attach:capsule.f90]. |
| 124 | | 1. Release and test tier 1 documentation.[[BR]] |
| 125 | | First step commited in perso/Martial.Mancip branch (opened). |
| 126 | | 1. Plan for tier 2 documentation. |
| | 128 | [[BR]] |
| | 129 | == SIMPLIFIED TICKET SERVER == |
| | 130 | 1. Organise documentation retreat (DONE) |
| | 131 | 1. Present documentation effort project at a reunion suivi (DONE) |
| | 132 | 1. Define standard header [attach:capsule.f90] (DONE). |
| | 133 | 1. Prepare examples and protocol (DONE) |
| | 134 | 1. Develop additional functionality if essential for tier 1 and tier 2 documentation (DONE) |
| | 135 | 1. Organize workload (DONE) |
| | 136 | 1. Follow-up of documentation effort (F.M./S.L. ONGOING) |
| | 137 | 1. Test tier 2 documentation. First step commited in perso/Martial.Mancip branch (M.M. ONGOING). |
| | 138 | 1. Compile tier 2 documentation (M.M.) |
| | 139 | 1. Prepare tier 3 documentation.(M.M., F.M. & S.L.) |
| | 140 | 1. Develop additional functionality for tier 3 documentation (M.M.) |
| | 141 | |
| 140 | | Actions |
| 141 | | * Technical: Propose a Module Header (F.M.). |
| 142 | | * Technical: Create a LaTeX file grouping all variables names/symbols used in equations in order to harmonize. If available, add the corresponding CMIP5 name, see [http://forge.ipsl.jussieu.fr/igcmg/wiki/IPSLCM5A/Sorties/EquivalenceIPSLCMIP5]. |
| 143 | | * Organization: Check if attendees need a Mission Order. |
| 144 | | * Organization: Constitute a Review Committee including possibly P. Ciais, G. Krinner, S. Piao, ... (S.L./M.M./P.P.) |
| 145 | | * Organization: Plan a second meeting early in January to ensure the preparation of the retreat is efficient. (F.M.) |
| 146 | | * Communication: A report could be presented at the end of the retreat to some VIPs (IPSL, LSCE, LMD). (P.P.) |
| 147 | | |
| 148 | | What P. Peylin would like all contributors to remember: |
| 149 | | * Better more than less. |
| 150 | | * Equations are very useful. |
| 151 | | * A flowchart is mandatory for all large subroutines. |
| 152 | | * DO NOT MODIFY THE CODE (only comments), but do not hesitate to do suggestions maybe in a separate file if you think about changing some variables names, modifying the structure to be more efficient (do/enddo, if/endif, ...), remove some obsolete code, ... |
| 153 | | |
