search

parflow / parflow

Parflow is an open-source parallel watershed flow model.
http://parflow.org
Other
163 stars 98 forks source link

Documentation restructuring and cleanup #330

Open smithsg84 opened 3 years ago

smithsg84 commented 3 years ago

ParFlow documentation has become a mess. It is scattered in multiple places and not consistent.

I'd like to pull apart this discussion a bit into separate issues so we can get consensus on path forward.

Documentation source structure/location
    Where we are putting documentation files
Format
    What file formats (Latex/restructured text)
Deployment
    Where we deploay documentation for users to access

Steve's strawman

This has two unanswered questions.

What format for user manual?

What standard for Python code documentation?

Documentation source structure/location

  1. README.md
    • A short description of PF and pointer to other documentation
    • build instructions are moved to the User Manaul
      • root/README.md
  2. User Manual
    • The current README file information on building PF
    • The current manual info exuding the pfkey reference material
    • src files are in docs/manuals
  3. PF Key Reference
    • Reference documentation for each pfkey*
    • source files in root/pf-keys/definitions
  4. Code documentation
    • Code developer documentation
    • Embedded in the code files
  5. Installation Guides
    • Parflow WIKI
  6. FAQ
    • ParFlow WIKI

Format

  1. README.md
    • Google markdown
  2. User Manual
    • ???
    • Currently Latex
  3. PF Key Reference
    • YAML format
  4. Code documenation
    • C/C++
    • Doxygen
    • Python
      • Currently mixed formats being used
      • Need a standard ???
  5. Installation Guides
    • Github WIKI
  6. FAQ
    • GitHub WIKI

Deployment

(1) Github repo

(3,4) on read-the-docs (3) as PDF

(5,6) on web page WIKI

(4) eventually on read-the-docs

reedmaxwell commented 3 years ago

thanks @smithsg84 for getting this rolling. I think this looks good and have some thoughts. Currently, we document the TCL PFTools in a chapter of the manual with examples, a table, and keys. I think the Python PFTools should be the same. The exception is I think some connection needs to happen between the sparse documentation in the keys themselves (which is better than nothing and a neat idea, but much less than what's in teh manual) and what the manual contains. That is, I think the information should be the same between them should synched up, and have one source. The formatting in the manual (key order, etc) is pretty differently organized than the read the docs is currently.

smithsg84 commented 3 years ago

From group discussion on 2021/05/05.

[ ] @smithsg84 Need to update strawman with:

  1. Studies/paper list should be moved to wiki for more dynamic editing.
  2. ParFlow web page should point to wiki for paper references
  3. Key librarary documentation is incomplete, needs to be synced with existing user manual (latex) information
  4. New manual outline
    1. PF manual
    2. PF tools manual
    3. Keys
smithsg84 commented 2 years ago

Some work on automating parflow manual to read-the-docs.

https://github.com/parflow/parflow/tree/read-the-docs

alanquits commented 2 years ago

Here are a few complaints I have about the user manual:

  1. Parts of it are outdated.
  2. Some explanations lack context.
  3. There are almost no figures.
  4. There are a lot of typos.
  5. It contains information that does not necessarily need to be in a user manual. ... I could go on

Most of these issues have a much better chance of being improved by migrating the working copy of the manual away from LaTeX and possibly out of the GitHub repo. Consider someone that is willing to proof-read or someone who is willing to make figures. Currently, that person needs to be able to use Git well enough to clone the repository, branch it, and submit a pull request. They also need to know LaTeX at least a little bit and be comfortable compiling it (that's not to mention the massive install). It's a high barrier to entry for someone who might just want to fix a misspelled word or two.

There are several ways to make editing easier. One that comes to mind is using something like a wikibook (e.g., https://en.wikibooks.org/wiki/Ada_Programming). Even switching to Markdown and rendering LaTeX later would make editing simpler for most people. That's just my opinion.

reedmaxwell commented 2 years ago

All good points, thanks for the feedback. We have a staff person (@amy-defnet) working on this doing this like migrating to an RST type format, cross checking the keys and providing more use cases.