Skip to main content
Version: 1.3.1

Documentation Governance & Guide

This master guide consolidates all information regarding the project's documentation lifecycle. It includes high-level governance policies, ownership models, and a step-by-step developer guide for adding new content, managing native versioning, and translating pages.

Part 1: Governance & Ownership​

Our documentation is the primary source of truth for users, contributors, and maintainers. To ensure quality, consistency, and accuracy, we adhere to the following principles.

Rules of Thumb​

  • User Docs: Update user-facing manuals immediately when any user-visible behavior, UI element, or setup step changes.
  • Technical Docs: Update technical and architectural documentation when code structure, API design, dependency structures, or release pipelines are modified.
  • Contributor Docs: Update contributor guidelines when workflow expectations, pull request checklists, or style guides change.
  • Homepage: Keep the main homepage focused on the product narrative and high-level onboarding, not deep implementation details.

Ownership Model​

We use a lightweight, distributed ownership model:

  • Information Architect: One maintainer acts as the custodian of the overall structure, homepage consistency, and navigation menus.
  • Feature Authors: Developers who implement a feature or change are responsible for writing and updating the corresponding documentation pages.
  • Reviewers: Pull request reviewers must ensure that documentation updates are included in the PR if the code changes warrant them.

Part 2: Step-by-Step Guide to Adding Documentation​

Adding new documentation to the website is a 5-step process:

Step 1: Create the Markdown File​

Create a new .md (or .mdx) file under the appropriate subdirectory of docs/:

  • docs/user/: For user guides, installation manuals, and user-facing troubleshooting.
  • docs/technical/: For architecture design, codebase organization, database schemas, and release steps.
  • docs/contributing/: For developer workflows, guidelines, and governance documents.

Add the required frontmatter at the top of the file:

---
title: My New Guide Title
sidebar_label: My Guide
description: A short description of the page content for search engines and SEO.
---

Step 2: Configure the Sidebar Navigation​

The sidebar navigation layout is defined in sidebars.js.

  1. Open sidebars.js.
  2. Locate the appropriate category (e.g., Functional, Technical, or Contributor).
  3. Add the relative path of your file (excluding the docs/ prefix and .md extension) to the items array:
    {
      type: "category",
      label: "Contributor",
      items: [
        "contributing/getting-started",
        "contributing/pull-request-guidelines",
        "contributing/documentation-governance" // Added here
      ]
    }
warning

If you are adding documentation to an archived release version (like version 1.2.9), do not edit files in docs/ or sidebars.js. Instead, see Part 3: Document Versioning below.

Part 3: Document Versioning​

This project uses Docusaurus native documentation versioning to archive historical states of the documentation corresponding to specific software releases.

  • Next (Active Development): Refers to files currently inside docs/ and configured in sidebars.js.
  • Archived Versions (e.g., 1.2.9): Frozen snapshots stored under versioned_docs/version-1.2.9/ and sidebar config versioned_sidebars/version-1.2.9-sidebars.json.

Lifecycle Diagram​

Modifying Versioned Docs (Version 1.2.9)​

To add or modify documentation specifically for version 1.2.9:

  1. Add/Edit the File: Create or modify the file under versioned_docs/version-1.2.9/contributing/ (or other subdirectories).
  2. Update the Versioned Sidebar: Edit the JSON configuration in versioned_sidebars/version-1.2.9-sidebars.json to register the file ID.

Cutting a New Version​

When preparing a new major/minor software release (e.g., 1.3.0), freeze the current state of documentation:

  1. Run the versioning command: 
    npx docusaurus docs:version 1.3.0

Part 4: Translation and Localization (i18n)​

The website currently supports English (en, source) and Dutch (nl, translation). All translation assets are stored in the i18n/nl/ folder.

Translating Markdown content​

To translate documentation or static pages, copy the source file to the corresponding localization directory and translate its contents:

Source File LocationDestination Translation Location
docs/contributing/guide.md (Next Docs)i18n/nl/docusaurus-plugin-content-docs/current/contributing/guide.md
versioned_docs/version-1.2.9/contributing/guide.mdi18n/nl/docusaurus-plugin-content-docs/version-1.2.9/contributing/guide.md
src/pages/index.js (Static React page)i18n/nl/docusaurus-plugin-content-pages/index.js

Translating UI & Sidebar Labels (JSON)​

  1. Extract new strings: If you have changed sidebar labels or UI code, extract them to JSON files: 
    npm run write-translations -- --locale nl
  2. Translate JSON entries: Open and update the "message" value in:
    • i18n/nl/code.json (theme elements, header/footer navigation items)
    • i18n/nl/docusaurus-plugin-content-docs/current.json (Next sidebar categories)
    • i18n/nl/docusaurus-plugin-content-docs/version-1.2.9.json (Version 1.2.9 sidebar categories)

Part 5: Local Development & Validation​

Before pushing any documentation modifications to production:

1. Install Dependencies​

Run this in the repository root directory to set up Docusaurus:

npm install

2. Start the Local Development Server​

  • Preview English: npm run start (available at http://localhost:3000/TimeManagement_Docs/)
  • Preview Dutch: npm run start -- --locale nl (available at http://localhost:3000/TimeManagement_Docs/nl/)

3. Run a Production Build Verification​

To ensure there are no syntax errors, configuration issues, or broken links:

npm run build

This command must run successfully without errors before a Pull Request is merged.