DR-008-Infra: Docs Modularity

Modularize docs		status: proposed
context: Infrastructure decision: tbd
dec_rec__infra__docs_modularity		Decision Record

Context / Problem

There is a proof-of-concept for an alternative documentation build concept introduced in tooling PR 95. It improves the modularity of documentation but drops features of the existing documentation concept.

Goals and Requirements

• Implementation Effort: Don’t spend much one-time effort to implement the change proposed here.

• Maintenance Effort: Don’t spend much ongoing effort due to increased complexity.

• Ease of use: Developers don’t like working on documentation, so we should make it easy on them.

Options Considered

Option S: Single docs() only

We keep the current docs-as-code concept and drop the PoC proposal.

Implementation Effort 💚 No additional effort.

Maintenance Effort 🤔 unclear in relation to PoC.

Ease of use 💚 No change for developers.

Option M: Many Bazel targets

We drop the current approach and switch to the PoC approach.

Implementation Effort 😡 Requires restructuring all documentation.

Maintenance Effort 🤔 unclear

Ease of use 😡 Requires developers to adapt to new workflow. No VSCode LSP integration.

Option C: Combine the Best of Both

We integrated the advantages of the PoC into the existing solution maintaining all benefits.

Implementation Effort 😡 Certainly the most effort

Maintenance Effort 😡 Certainly the most effort

Ease of use 💚 No mandatory change for developers at first but extensions?

Evaluation

Here is the summary, how well each option achieves the goals in order of goal importance:

Goals	Option S	Option M	Option C
Implementation Effort	💚	😡	😡
Maintenance Effort	🤔	🤔	😡
Ease of use	💚	😡	💚

Decision: Option S has no downsides while the alternatives do.