logo

Documentation Standards ​

Purpose ​

Our primary aim for documentation is to provide clear and comprehensive guidance for our internal developers. Good documentation ensures that our team has a thorough understanding of our codebase, enabling them to develop features and debug issues efficiently.

Tools and Platforms ​

  • Project-Specific Documentation: This is maintained directly within the code repository. This ensures that our documentation stays in sync with our code and facilitates versioning.

  • Global Documentation: Our overarching company documentation resides in a VuePress application. This can be accessed and contributed to at our InnoGE GitHub repository.

Writing Style and Grammar ​

To ensure clarity and professionalism in our documentation, we utilize Grammarly for grammar checks and stylistic improvements. Developers are encouraged to use Grammarly to review and refine their documentation contributions.

Versioning ​

Given that our documentation is integrated with our code, versioning is inherently managed through git. As such, when we tag a release in our software, the corresponding documentation for that version is effectively tagged as well.

Detailing and Comments ​

  • Code Comments: We expect developers to only comment on more complex parts of the code. If the code's purpose and functionality are evident at a glance, it doesn't need commenting. However, intricate logic or non-obvious implementations should be thoroughly commented for clarity.

  • Higher-Level Documentation: For broader topics and overviews, documentation should be stored in the /documentation folder within the project.

API Documentation ​

We rely on Postman for API documentation. This provides a hands-on, interactive way to understand our API's capabilities and constraints.

Responsibility and Updates ​

Developers engaged in the projects bear the responsibility for updating documentation. When introducing or modifying features, it's crucial to ensure the documentation is updated correspondingly. This practice ensures that our codebase and guidance stay in sync, providing a reliable reference point for the entire team.

Review Process ​

Documentation updates undergo a review process similar to code changes. This review takes place during the usual code review phase, ensuring that our documentation maintains its clarity, accuracy, and relevance.

Consistency Across Projects ​

To maintain consistency in documentation across various projects and teams:

  • Adhere to a shared structure: Begin with setup instructions, followed by architectural decisions, and then delve into specific features.
  • Use a unified tone and style: While we don't enforce strict conventions, striving for a consistent tone ensures our documentation reads seamlessly across projects.

Must-Have Topics ​

Every project documentation should at least cover:

  • Setup Instructions: A clear guide on setting up the project for development, including dependencies, configurations, and any other prerequisites.

  • Architectural Decisions: An overview of significant decisions made regarding the system architecture, the reasons behind those decisions, and their implications.