Pecan: Documentation Outline

@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.

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.

@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.

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.

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

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.

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

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.