Climatemachine.jl: Documentation

[simonbyrne]

• Document what each module does
• Link to design docs?
  
  
  
  • Dedicated software design docs
  
  
• Onboarding docs
  
  
  
  • What are our systems and processes
  
  
  • Development guide
  
  

[trontrytel]

The documentation needs for a new user and a new developer are different. Do we want to have one docs for both cases or we want to separate it somehow?

[leios]

I think Oceananigans has provided the foundation for how to start documenting CLIMA (here are their docs)

I believe we are missing the following:

1. General intro to the goals of CliMA, including a table of contents for the docs and a link to the overleaf document
2. Installation instructions (Eventually we would like to make CLIMA a julia package to make this easier)
3. Simple examples that can be run (really, just re-purposing the examples directory)
4. A developer guide with
   
   
   
   1. Consistent Style Guide
   
   
   2. Point of Contacts for particular elements of the codebase
   
   
   3. Any technical issues that need elaboration (MPIStateArrays, for example)
   
   
   4. Current pushes for CLIMA and intended future developments
   
   
   5. An API that is preferably generated by maintained comments in the code
   
   

Additions:

1. Discussion of GPU vs CPU for computation and the architecture supported by CLIMA
2. Code of Conduct (maybe unnecessary, but I know people who will not commit to an OSS project without one)

I could have missed some stuff, so please add to this list. I don't mind starting on the documentation soon.

[trontrytel]

Happy to help with that

[simonbyrne]

Good guidelines for documentation:
https://www.divio.com/blog/documentation/

[charleskawczynski]

Good guidelines for documentation:

Couldn't agree more, fantastic talk.