Skip to content

documentation-process.md

Latest commit

 

History

History
43 lines (27 loc) · 3.67 KB

documentation-process.md

File metadata and controls

43 lines (27 loc) · 3.67 KB
Raw

Documentation Maintenance Process

To ensure the AgentSimMiddleware project's documentation remains accurate, comprehensive, and up-to-date with the codebase, the following process will be adhered to:

1. "Documentation as Code" Principle

Documentation is considered an integral part of the codebase. Any modification to the source code that impacts the public API, core architecture, or key operational aspects must be accompanied by a corresponding update to the relevant documentation files. This applies to:

  • docs/API.md for C++ and C# public interfaces.
  • Other files within the docs/ directory for architectural overviews, integration guides, or design decisions.
  • Inline code comments (docstrings/XML comments) for clarity and maintainability.

2. Pull Request (PR) Requirements

All Pull Requests (PRs) modifying source code will be subject to the following documentation checks:

  • Mandatory Documentation Review: For every PR that includes changes to src/cpp/ or src/csharp/, a human reviewer is required to explicitly verify that all relevant documentation in docs/ has been updated appropriately. This check will be an mandatory item in the PR review checklist.
  • Explicit Documentation Statement: The PR description for any code change affecting a public API (C++ AGENTSIM_API functions, public C# classes/methods, enums, structs) must explicitly state:
    • Which sections of API.md (or other docs/ files) were updated to reflect the code changes.
    • A clear justification if no documentation updates were deemed necessary for the given code changes.

3. Scheduled Documentation Review Cycles

To proactively address potential documentation drift and ensure overall quality:

  • Quarterly Audit: A designated team member or architect will conduct a comprehensive audit of the entire docs/ directory on a quarterly basis. This audit will verify the accuracy, completeness, and clarity of all documentation against the current state of the codebase.
  • Focus Areas: Special attention during these audits will be given to areas of the codebase that have undergone significant development, feature additions, or major refactoring in the preceding quarter.

4. "Documentation Debt" Tracking

When outdated, inaccurate, or missing documentation is identified (either during code reviews, scheduled audits, or ad-hoc discovery):

  • Issue Creation: A dedicated issue (e.g., in GitHub Issues, Jira, etc.) will be created. This issue will be assigned a high priority and directed to the relevant team member(s) responsible for the affected code or documentation area.
  • Resolution: The assigned individual(s) are responsible for addressing the documentation debt in a timely manner.

5. Tooling Investigation (Future Consideration)

The project will investigate the integration of automated tooling to further enhance documentation quality and maintenance. Potential tools include:

  • Static Analyzers: Exploring custom static analysis tools (e.g., Clang-Tidy for C++, Roslyn analyzers for C#) that could detect public API signature changes without corresponding documentation updates.
  • Docstring/XML Comment Enforcers: Integrating tools to enforce minimum coverage and proper formatting of inline docstrings (C++) and XML comments (C#) for all public symbols.
  • Version Control History Analysis: Developing custom scripts that analyze git diff outputs to cross-reference public API changes against documentation updates, flagging potential inconsistencies.

By implementing and adhering to this process, the AgentSimMiddleware project aims to maintain high-quality, reliable documentation that accurately reflects the evolving codebase.