Documentation Outline

[tonygardella]

Description

Proposal of High level Documentation Reorganization

Proposed Solution

Landing page

Tutorials/Demos/Workflows

• Installation
• User demos
• Developer Workflows

Topical pages

• Overall design of PEcAn
• PEcAn workflow
• Pecan xml
• PEcAn and BETY
• PEcAn-Docker
• PEcAn-SHINY
• PEcAn Standard Formats

Appendix

Explanation of content in each

Landing page

• Intro, links to papers, explain organization of book, explain how to edit book

Tutorials/Demos/Workflows

• Installation - List install methods and have common install problem section.
• User demos/workflows - Table with Tutorials/vignettes. and then list in order from beginner to advanced. Also make sure to Link to relevant info in the BETY Documentation(We do not want to double up on writing BETY documentation).
• Developer Workflows - How to add models, formats, inputs, use git for pecan, etc.

Topical pages

• Pages explaining the main parts of PEcAn that the workflow and demos pages can reference when explaining PEcAn

Appendix

• Link to package documentation and other external information. FAQ section.

[tonygardella]

@robkooper and @ashiklom Tried to combine your two ideas of an outline. @KristinaRiemer and @bailsofhay would be good to get your feedback. Going to start implementing this soon so we can have the pages moved to where we want before the end of the month.

[KristinaRiemer]

I think this looks really good. This is just rearranging existing material, not adding anything?

When you're doing this, chapter 41 should actually go before 40.

[tonygardella]

@KristinaRiemer Yeah I'm going to just going to move things around. In the meantime we can identify things that are missing and make issues. Note that this is labeled as an "Epic" issue so these other issues can be linked under this Issue so we can stay organized.

[bailsofhay]

I was just looking around the documentation for some lingo to use in a quick write up about what I do. I realized that the doc doesn't have the best explanation for why someone would want to use pecan (specifically it's missing any explanation for the uncertainty analysis). This would make sense to put in the "Project Overview" section of the current available doc, not sure about where to add this for the reorganized one we're working on.

[tonygardella]

Link from @infotroph about documentation: https://www.divio.com/blog/documentation/

[infotroph]

Link from @infotroph about documentation: https://www.divio.com/blog/documentation/

More context: This piece makes a strongly-argued case that there are four distinct types of software documentation, and that all well-documented projects need to have all four of them as explicitly separate sections:

• tutorials, for teaching beginners what your tool does using step-by-step examples that are guaranteed to work exactly as described every time
• how-tos, the cookbook section where users can go to answer questions of the form "How do I....?", containing only the details they need for a given question
• reference, for the man-page details on how to call things, what protocols they speak, and what values they return
• discussion, where you explain why things work they way they do, provide background information, advise on good vs bad practices, and otherwise give context that don't fit in the other sections.

[github-actions]

This issue is stale because it has been open 365 days with no activity.

[infotroph]

Long-term, I think the tutorial/how-to/reference concept is solid and that we could still clarify the docs by applying it more uniformly. But the reorg originally discussed here has been implemented fully enough that I'll close this issue and encourage new threads for any further cleanup.