Rearrange documentation and add "learn the workflow" section

[Lotes]

I reorganized the documentation in this PR. I do not want to delete any existing pages, but sometimes they are a bit long and misleading. Most of them are fine for me.
I also added a learning section where (new) the basic workflow with Langium gets explained.

• everything from "old/Guides" you can find under "new/Recipes"
• everything from "old/Tutorials" you can find under "new/Learn/Minilogo"
• everything from "old/Documentation" got intermixed (WIP)
  • "old/Documentation/Langium Overview" you can find under "new/What is Langium/Features"
  • "old/Documentation/Getting started" you can find under "new/Reference/Glossary" and several "new/Learn/Workflow/*"
  • the remaining part of "old/Documentation" you can find under "new/Reference"

[github-actions]

PR Preview Action v1.4.6
Preview removed because the pull request was closed.
2024-05-14 11:37 UTC

[JohannesMeierSE]

@Lotes I wrote a tutorial about keywords as identifiers in #219, but it is not yet merged. Maybe it belongs to "Recipes"? It could be seen as a tutorial as well, but it is not related to Minilogo, therefore "Minilogo tutorial" would not fit as category.

[Lotes]

@JohannesMeierSE

I would put it under recipes, since it is not really learning the workflow, it is some kind of feature you want to talk about.

The Minilogo tutorial is also some kind of learning + multiple recipes, and I think maybe we should adapt it to fit more with the workflow. On the other hand... each project has its own challenges and therefore differs from the core workflow.

[JohannesMeierSE]

I got some ideas in detail:

• I would place "Code Bundling" as last point in "Recipes", since it is the final thing you would do. Having "Scoping" as one of the most important things at position 1 makes sense for me.
• At the moment, "Documentation" is an empty page: Maybe, we could place here some tips, when to read which parts of the documentation?

Regarding "Our Workflow":

• I would rename it to "Langium's Workflow", since I don't like "Our", that sounds a bit like suggestions of TypeFox.
• Adding numbers 1, 2, 3, ... before the names in the outline/TOC in the left side bar would improve the readability and the steps.
• Having the names in the workflow diagram and in the side bar 100% the same makes it easier to match the steps.

For the "Workflow diagram":

• I would treat "Find advanced topics" not as a step, in particular, not as the picture suggests: After applying an advanced topic, you cannot iterate your DSL anymore (that is, what the diagram tells the reader). You want to say, that there is much more, which does not fit into these seven steps. Therefore, I suggest to say, that these 7 steps reflect the base workflow, in particular, for becoming familiar with Langium, but there are much more advanced topics in "Recipes".
• Maybe, you could have a dedicated section for the "Initial Set-up" before the section for the "Core workflow"? Than all steps are visually represented in the same way.

Nevertheless, I like your clear steps a lot and I think, they will help newcomers a lot!
My comments target only some details of the updated documentation structure.

[Lotes]

Thank you, @JohannesMeierSE . I made all these changes.

[Lotes]

Add a hint on names for resolving scope. The name is the key to resolve cross-references.

[gfontorbe]

I really like the new flow of the documentation! Thanks a lot @Lotes.

Just a couple minor suggestions

[insafuhrmann]

Thank you very much for your PR, @Lotes. I like the new flow very much and also the additions you made. I just added a few detail remarks.