In #369, I said that I thought the organisation of the documentation could be better. I wanted to put an issue together to discuss how I think that reorganisation might happen and whether the development team think what I have in mind is good / bad / needs improvement.

I would like to split the documentation into 3 tables of content (TOCs), rather than just one as it is at the moment, which reflect the broad scope of the documentation. These three TOCs would be "Introduction", "User Manual" and "Development" (I'm not wedded to these titles). Below these categories, I think the docs should be organised like this:

• Introduction
  • Overview
    • This is a new section that would describe things like the advantages of using WEC-Sim over other methods
    • Show some examples of what WEC-Sim can do
  • Webinars
  • Publications
  • Acknowledgements
  • Release Notes
    • Not sure about where this one should go...
• User Manual
  • Getting Started
  • Tutorials
    • I always think tutorials should be upfront and self-supporting. They should offer a taster and direct people to dive deeper, where needed.
  • Workflow
    • Was Overview, but with WEC-Sim Development removed
  • Code Structure
  • Advanced Features
  • Theory
  • Terminology
• Development
  • Overview
    • This can be the WEC-Sim Development section for starters
  • API
    • My feeling is that this is more aimed at developers rather than the user. The Code Structure section can direct here, if necessary.
  • License

For me, this (mostly) neatly splits the documentation into three types of people: people who want to know about WEC-Sim, but maybe not use it, yet; people who want to use WEC-Sim, but not develop it; and people who want to develop WEC-Sim.

Interested to hear your thoughts.