Skip to main content

Documentation Guidelines

This document outlines the standards and best practices for creating, maintaining, and organizing documentation within the WEP-IT-Docs repository. Following these guidelines ensures consistency, readability, and a professional appearance across all technical documents.

1. Tone and Style​

  • Professional & Objective: Maintain a neutral, professional tone. Avoid slang or overly casual language.
  • Clarity & Conciseness: Use clear, direct sentences. Avoid unnecessary jargon. If a complex term is necessary, provide a brief explanation or a link to a glossary.
  • Active Voice: Use the active voice where possible (e.g., "The integration hub processes the request" instead of "The request is processed by the integration hub").
  • Language: All documentation should be written in English to ensure accessibility for all current and future technical stakeholders.

2. Formatting (Markdown Standards)​

  • Hierarchy: Use a single H1 (#) for the main page title. Use H2 (##) and H3 (###) for logical sections.
  • Lists: Use bullet points for features/items and numbered lists for sequential steps.
  • Code Blocks: Use triple backticks (```) with the appropriate language specifier (e.g., mermaid, json, bash) for technical snippets or diagrams.
  • Bold/Italics: Use bold for key terms, UI elements, or important warnings. Use italics for emphasis or book/tool titles.

3. Diagrams and Visuals​

  • Mermaid.js: Whenever possible, use Mermaid code blocks within Markdown for sequence diagrams, flowcharts, and architecture maps. This makes them searchable and easy to update.
  • Image Storage: If static images (PNG, SVG) are necessary, store them in the 00-Meta/03-Assets directory and reference them using relative paths.
  • Naming Convention: Use descriptive, kebab-case names for assets (e.g., enrollment-workflow-v1.png).

4. Maintenance and Versioning​

  • Keep it Current: Documentation should be updated concurrently with system changes. Outdated documentation is often worse than no documentation.
  • Review Cycle: Periodically review high-level architecture documents (at least once per quarter) to ensure they still reflect the production state.
  • Change Log: For major architectural changes, consider adding a "Last Updated" date or a small change log at the bottom of the document.

5. Repository Structure​

  • Respect the existing directory hierarchy:
    • 01-Architecture for high-level concepts.
    • 04-Systems for technical details of specific tools.
    • 02-Processes for workflows.
  • Always include a README.md in every new subdirectory to explain its purpose.