Link Search Menu Expand Document
moja global

Agree on a Science Design

moja global tools have to be in line with the latest science and international standards. Therefore all code is informed by a science design stored in the Science folder of each repository. Code revisions might require a revision of the science design. When in doubt, ask the @TSC or just follow the procedures below.

  1. Invite Your Team
    • When you start a new project and are inviting your team to join, make sure that you invite (at least 1) accomplished scientists to review or develop a Science Design
    • If according to your scientist your project does not need changes to the existing Science Design, write a short justification mentioning the version of your feature or project in the title and submit a pull-request to the folder with the existing Science Design. Request @TSC to review your pull-request.
    • If according to your scientist your project requires a (revision of the) Science Design, proceed with the next step
  2. Create a Google Doc for the Science Design
    • Make a copy of the existing Science Design and change the version in the title.
    • If no Science Design exists yet, copy the standard header into a new Google Doc, copy the Title and Abstract from the GitHub repository and add the version to the title.
    • Copy the link to the Google Doc with Editing permission back to GitHub in a file with the same name and version in the Science Folder of the Project so visitors can easily find the Google Doc
  3. Appoint Maintainers and Editors
    • Every document should have ideally 2 maintainers and/or editors. The Maintainers focus on the substance of the document. The Editors focus on the readability of the document. Two editors and two maintainers are ideal so they can review each other’s suggestions. Having 2 persons with combined maintainer/editor functions can be sufficient for projects with a small science component.
    • Add the names to the header of the Google Doc
  4. Invite Collaborators
    • Reach out to all the collaborators that could be interested to make a contribution. Bigger and more diverse groups tend to come up with better designs. Different levels of expertise are also a bonus.
    • Set the Rule of Collaboration on text use this standard list of rules as a basis
  5. Agree on Report Structure
    • Develop a brainmap: Ask the collaborators to add key topics that the science design needs to cover. Ask them to progressively group the topics into a logical structure. (see page 2 of the Standard Header Doc)
    • After a reasonable amount of time, ask all collaborators for their final suggestions and fix the report structure. (This does not mean that this structure is final. Changes are always possible. It is more important to have a first structure within a reasonable amount of time than to invest in the ideal structure for too long.)
  6. Draft Science Design
    • For each section of the report a drafter is appointed. This drafter will produce the first version of the section by an agreed date.
    • All other contributors can comment or suggest.
    • The editors will write the background, acknowledgements, etc. and they will edit the text already written. (Editing is not rewriting! Rewriting can confuse and discourage the drafter.)
    • Invite all collaborators to provide edits and comments by a specific date.
  7. Release Science Design
    • After the final date agreed for the draft, the Science Design is copied (with comments) into a Google Doc with the same title but with a Release Candidate Version.
    • All remaining comments are dealt with by the drafters and the maintainers. Additional comments are not allowed except if they point out errors.
    • The final draft is edited.
  8. Review and Approval by Science Panel
    • A Science Panel consists of at least 1 expert recognized as an authority in the field
    • The Science Panel reviews the Science Design Release Version. Maintainers make improvements and provide responses.
    • When there are no further comments, the Science Panel provides a short opinion at the end of the Science Design.
    • The final version including the Science Panel opinion are downloaded as PDF with the same title but with a Master Version.
  9. Approval TSC