document current setup

[AlexanderLanin]

Especially since we have some new people joining our ranks, but also in general, we need to describe how the current tooling is set up.

Specifically (to be extended):

• How is docs-as-code set up (bazel integration, esbonio setup, score_metamodel, _tooling directory, ...)
• What is the goal for multi repo docs output? multiple webpages? single page? compare Document current concept for multi repo dependencies #218

Current approach: so far we document such things in README.md files in the respective directories.

[AlexanderLanin]

Decision Record: Where to Document

Documentation Structure

• Guidance and Usage Instructions → guidance/*.rst
  This is where we document how to use our tools.

• Tool Architecture, Concepts, and Decision Records → README.md (next to the source code)

  • This follows the convention of placing a README.md in each directory.
  • It ensures easy discoverability and avoids burying critical information deep within documentation.
  • Additional .md files can be used as needed. Potentially in sub directories. Potentially in docs subdirectory.

Rendering to the Final Website

Both categories will be rendered via Sphinx. While detailed technical documentation (e.g., "how the tools work") may not be directly relevant to the website users, we still want to use our own tooling to assess usability firsthand within our team.

As a small compromise, we will evaluate using Markdown within the /docs/_tooling and /tools/ directories. See #156 for further details.

Participants: @AlexanderLanin @MaximilianSoerenPollak

Please copy this to /docs/_tooling/decision-records/