Repository navigation
document current setup #245
Description
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.
Activity
AlexanderLanin commentedon Jan 29, 2025
Decision Record: Where to Document
Documentation Structure
Guidance and Usage Instructions →
guidance/*.rstThis is where we document how to use our tools.
Tool Architecture, Concepts, and Decision Records →
README.md(next to the source code)README.mdin each directory..mdfiles can be used as needed. Potentially in sub directories. Potentially indocssubdirectory.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/_toolingand/tools/directories. See #156 for further details.Participants: @AlexanderLanin @MaximilianSoerenPollak
Please copy this to
/docs/_tooling/decision-records/