chore: Recreate documentation structure

[see7e]

Problem

The current documentation doesn't reflect all the iteration between the modules or it has some diagrams spreaded accors some diferent docs. This makes a little bit hard to understand the inter module communications, inside the bigger picture which is the Magma architecture itself.

Solution

A possible aproach is - as Jack the ripper, piece by piece - breaking from the higher components to the smaller modules and creating links in the documentation of each component (which has a lot of information already).

This way we can create a depper visualization not alone for each module but also with the information exchange between them.

Another bonus of that is to identify duplicated components and mark them for a possible refator in the future, or even find "undocumented features".

Non-goals

Anything specifically excluded from the concept

[lucaaamaral]

The best structure I have in mind follows:

• Top items - introduction content. Bottom items - specialized contend. Meaning that the average person should be able to read through the first pages with no problem, but they progressively get harder to understand, requiring more and more context.
• Let's avoid repeating explanations. It is a good thing to educate the users with progressively more information as he goes over the documentation, but let's not repeat things over and over again throughout the documentation. For example, when talking about the Magma's deployment, we can and should add a reference link to the explanation on what the user is doing - when installing the AGW, add a link to the AGW documentation, where is explained what is the AGW, what it does, what are its components and the relationship between these components, same applies to orchestrator and NMS.

With that in mind, we might end up with a structure somehow like the one below:

• Introduction (page)
• Deployment [content: Community validated scenarios] (page)
  • Orc8r
    • Kubernetes (page)
    • Docker (page)
    • Baremetal (page)
  • AGW
    • Kubernetes (page)
    • Docker (page)
    • Baremetal (page)
  • FEG
• Configuration
  • First time set up
  • Enabling 5G
  • [...]
• Magma use cases
  • Federation Gateway integration [example]
  • Cwag integration [example]
  • Edge computing setup [example]
  • Controlling drones [example]
  • [...]
• Technical reference [content: overview of magma architecture] (page)
  • Orc8r (page)
  • AGW (page)
  • FEG (page)
• Contributing [content: link to github/slack, link to deployment] (page)
  • Devcontainer (page)
  • Compiling & upgrading AGW (page)
  • Compiling & upgrading Orchestrator (page)
  • Incentive to "good first issue" and attendance to meetings

[There is always room for improvements]

[jorgevargasmor]

We can add these to the structure:

• Use cases of magma core.

• Tutorials for magma configuration.

[lucaaamaral]

Objective is to think on the user goal when visiting the documentation,

• deployers want to deploy,
• debuggers want to debug and
• developers want to develop.

Consider also including

• Document development worflows -
  • devcontainers
  • container updates
• Document and incentive on "good first issue"

[lucaaamaral]

I have just updated my first comment on this issue, detailing a bit more on the desired structure.