search

CliMA / ClimateMachine.jl

Climate Machine: an Earth System Model that automatically learns from data
https://clima.github.io/ClimateMachine.jl/latest/
Other
453 stars 78 forks source link

Documentation #744

Open simonbyrne opened 4 years ago

simonbyrne commented 4 years ago
trontrytel commented 4 years ago

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 commented 4 years ago

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 commented 4 years ago

Happy to help with that

simonbyrne commented 4 years ago

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

charleskawczynski commented 4 years ago

Good guidelines for documentation:

Couldn't agree more, fantastic talk.