Plan for general restructuring of documentation

[tmadlener]

This is a (potentially top-level) issue to discuss and plan for a general restructuring of the main documentation page. The current version is broadly organized into

• Instruction
  • General overview, getting started, contribution guide
• How-Tos and Instructions
• Tutorials
• Developing Key4hep
• Building Key4hep
• Publications
• (Call for logos)
• External Links

There is quite some overlap between some of the points and I would like to propose a some restructuring, something like:

• High Level Introduction (keep as is for now; Potentially extend some details a bit by lifting parts of it from below)
• Dedicated introduction pages for the main packages, introducing the main principles and components. Can also be a link to external sources if it exists
  • EDM4hep and podio
  • DD4hep (?) & k4geo
  • Gaudi (main parts, architecture)
  • k4FWCore (focus on Functional bits and things that are added on top)
  • k4MarlinWrapper (?)
• How-To pages with a curated list of (well contained) tasks or questions.
• Tutorials that cover specific workflows from start to finish

[m-fila]

I remember people telling me that they were confused by placement of content in the directories "How-Tos and Instructions", "Tutorials" and to some degree "Developing key4hep"

Maybe something like User Guide, Developer Guide, Tutorials could bring some clarification

[m-fila]

Also I think the complain I heard the most was that it's impossible to find a section how to read the bloody edm4hep files in C++ and Python