01_documentation_standards

Documentation Standards

This document sets the standard for creating and maintaining documentation. Clear and consistent documentation is crucial for collaboration, onboarding, and long-term project success.

General Principles

• Audience-Focused: Write for the intended audience. A client document will have a different tone and level of technical detail than internal developer documentation.
• Clear and Concise: Use simple language and avoid jargon where possible. Be direct and to the point.
• Up-to-Date: Documentation should be reviewed and updated regularly, especially when changes are made to the project. Outdated documentation is worse than no documentation.
• Accessible: Store documentation in a centralized and accessible location for all team members.

Documentation Types

1. Project Documentation

• Purpose: To provide a comprehensive overview of a project.
• Content:
  • Project goals and objectives.
  • Scope and requirements.
  • Design documents (wireframes, mockups).
  • Technical architecture and decisions.
  • Deployment and maintenance guides.
• Location: Project’s folder in the shared document repository (e.g., Confluence, Google Drive).

2. Technical Documentation (in Code)

• Purpose: To explain the code to other developers.
• Content:
  • Code Comments: Use comments to explain the why, not the what. Explain complex logic, assumptions, and trade-offs.
  • README.md: Every project/repository must have a README.md file with:
    • A brief description of the project.
    • Instructions on how to set up and run the project locally, referencing the general Local Development Environment Setup guide.
    • A summary of the tech stack.
    • An overview of the project structure.
    • Links to other relevant documentation.
• Location: Within the codebase itself.

3. API Documentation

• Purpose: To explain how to use an API.
• Standard: Use the OpenAPI (Swagger) specification.
• Content:
  • Authentication methods, following our Web Security Best Practices.
  • A list of all available endpoints.
  • For each endpoint:
    • The HTTP method (GET, POST, etc.).
    • The URL path.
    • A description of what it does.
    • Required parameters and their types.
    • Example request and response bodies.
    • Possible error responses.
• Location: Published to a stable URL, accessible to developers.

Formatting

• Markdown: Use Markdown for all text-based documentation.
• Headings: Use headings (#, ##, ###) to structure the document and create a table of contents.
• Code Blocks: Use code blocks with syntax highlighting for code examples.
• Images: Use images and diagrams to illustrate complex concepts. Store images in a sensible location and use relative paths if possible.