Skip to content

1.3 Documentation Contribution

Documentation is part of how Moonitoring designs and operates systems, not something added after the work is finished. This site is the shared single source of truth for agreed context, expected behavior, constraints, and decisions that apply across the company.

Before planning or implementing a meaningful change, begin with the relevant documentation. It should help you understand what is already known, what has been agreed, and which questions still need an answer.

Document before implementing

The relevant documentation should describe the agreed direction before implementation begins. When that direction changes, update the documentation as part of the same work so that it remains trustworthy.

1.3.1 Writing Documentation

Write for someone who does not yet share your context. Start with the reason a topic matters, then introduce its behavior and constraints before moving into implementation details. A page should normally progress in this order:

  1. Context and purpose.
  2. Expected behavior.
  3. Decisions and constraints.
  4. Technical details and examples.

Open every page and section with a short, non-technical summary that anyone in the company can follow. Bring in technical detail gradually, only where the reader needs it.

Keep pages concise. Write what the reader needs to understand or act, and leave out the rest.

Make every page accessible to readers without a technical background:

  • Link the first mention of a concept that is documented elsewhere.
  • Spell out acronyms at their first use, and add recurring ones to docs/includes/abbreviations.md so every page explains them on hover.

Prefer updating the existing authoritative page instead of repeating the same information elsewhere. If two pages explain the same fact, readers cannot know which one to trust when they eventually disagree.

Company-wide knowledge belongs in this documentation. Information that applies only to one project belongs alongside its code in that project's repository, under the docs/ directory.

1.3.2 Page Metadata

Every page must define at least one writer and one owner. A plain name is sufficient:

writers:
  - Jane Doe
owners:
  - Platform Team

Use a GitHub username to link the profile and load its avatar automatically. An explicit HTTPS image URL overrides the GitHub avatar:

writers:
  - github: octocat
  - name: Jane Doe
    avatar: https://example.com/jane.webp
owners:
  - name: Alex Smith
    github: alex-smith

Each list can contain multiple people. An entry with avatar must also provide name or github so the identity remains accessible when the image cannot load.