Skip to content

Maintain and translate

Documentation is part of the project: each change should be traceable to an implementation, a confirmed decision or a clearly labeled proposal. Updating Spanish and English in the same merge request prevents the two languages from describing different behavior.

Source organization

Location Purpose
docs/es/ Spanish content
docs/en/ English content at matching paths
docs/assets/ Shared content diagrams and images
theme/assets/ CSS, logo and local Mermaid runtime
theme/overrides/ Small theme adaptations
mkdocs.es.yml, mkdocs.en.yml Translated navigation menus
third_party/ Licenses and provenance of redistributed assets

The build includes shared assets in both sites. Edit their source once. public/ and .build/ are outputs; a change made directly to them disappears during the next build.

Change or add a page

  1. Create a documentation branch, such as docs/update-infrastructure.
  2. Edit the Spanish file and its English counterpart. Preserve the same relative file name and path, for example infrastructure/state.md.
  3. If adding a page, list it in both mkdocs.es.yml and mkdocs.en.yml, with an appropriate title in each language.
  4. Review links and references affected by the change.
  5. Run a complete build and visually inspect the changed pages.
  6. Open a merge request explaining the documented behavior, its source and any unresolved decision.

A missing translation is not silently replaced with filler content: the parity check fails. This exposes omissions before publication.

Use verifiable evidence

When updating Terraform, CI/CD or Kubernetes details, retain the repository name, file path and reviewed commit. Prefer a permanent /-/blob/<commit>/<path> link to a mutable branch link whenever possible.

For a thesis claim, cite the chapter or section and page; distinguish the PDF page number from printed pagination when they differ. The thesis map and sources page organize those mappings.

Keep the following distinctions explicit:

Evidence type How to present it
Observed implementation Describe the behavior and cite the file and commit.
Thesis statement Attribute the statement to the document and retain its reference.
Interpretation Explain the reasoning and identify what was not directly verified.
Proposed improvement Mark it as a proposal instead of an existing feature.
Unknown design rationale Record it as a question for the author or a pending decision.

A pipeline file shows what is configured but does not itself prove that a job completed successfully. A Terraform resource declares intent but does not prove that the resource still exists in a cloud account. Execution evidence needs a date and a specific source.

Style and translation

  • Write for someone who needs to understand, reproduce or operate the project.
  • Preserve job names, variables, paths, resources and commands exactly as they appear in the source.
  • Translate explanations and titles, not technical identifiers.
  • Explain the purpose before commands or implementation details.
  • Use a table for concrete mappings of variables, environments, jobs or resources.
  • Label example values and parameters that a reader must replace when reproducing a deployment.
  • Keep both versions equivalent in scope, including limitations and unanswered questions.

Translations can have different heading anchors because their titles differ. Link to the appropriate heading within each language. The language selector preserves the page; it does not automatically translate an individual fragment.

Links between pages use relative Markdown file paths:

[Terraform state](../infrastructure/state.md)
[Publication](publishing.md)

MkDocs converts these paths into site URLs and validates their destinations. Avoid links into public/ or hardcoded URLs beginning with /en/: an absolute root can discard a project's Pages subpath.

Write Mermaid diagrams in fenced code blocks. Keep each diagram focused on one relationship and switch to a vertical layout when it becomes too wide:

```mermaid
flowchart TD
  C[Commit] --> V{Validation}
  V -->|Pass| P[Publish]
  V -->|Fail| R[Review]
```

The runtime is distributed within the repository, so viewing a diagram does not require a CDN. Diagrams should reflect the reviewed implementation and distinguish proposed architecture from the current design. Provide equivalent surrounding text so the explanation remains understandable without the image.

Shared original assets can live under docs/assets/. From a page under docs/en/infrastructure/, for example, docs/assets/diagrams/network.svg is linked as ../assets/diagrams/network.svg after the build copies it into the language root. Markdown paths are interpreted relative to the page location.

Validate before merging

With the virtual environment already installed:

.venv/bin/python scripts/check_docs.py
.venv/bin/python scripts/build_docs.py

The first command provides a quick source check. The second includes that check and validates the build and generated HTML. Running the second command is sufficient for a normal review.

Strict mode turns navigation and link warnings into build failures. The additional validation also checks language-switch links and static assets. Review external links separately when a change affects their contents or destination.

To inspect presentation:

.venv/bin/python scripts/build_docs.py --serve

Check the title, code blocks, table and diagram widths, language menu and a narrow viewport. The generator checks paths and structure; visual review checks whether the explanation is readable.

Update the toolchain

requirements.in lists direct dependencies. requirements.txt pins the complete set tested on Python 3.12; CI installs the latter. Update both deliberately on a branch, then build the complete site in both languages before merging. The CI image follows python:3.12-slim, so base-image updates can still arrive.

The selected theme is Material for MkDocs 9.8.0. Its project announces maintenance until May 5, 2027; plan a theme review before that date while retaining the Markdown sources and MkDocs as the requested generator. This date concerns the theme, not the support status of every dependency. Maintainer notice on PyPI.

The bundled Mermaid runtime records its version, origin URL and integrity in third_party/mermaid/version.json. When replacing it, retain its license and verify a diagram page. The adapted Material templates also retain their license under third_party/.

What a merge request should explain

Describe the behavior change or documentation correction, the sources reviewed and the build result. If a decision is unconfirmed, reference the corresponding question under Decisions. A documentation merge request should not turn a hypothesis into a conclusion or claim deployment results that were not observed.