Good documentation is essential for ensuring code maintainability and ease of understanding for future developers (including the future YOU). Here are some guidelines we follow:

• Index Page: A central hub for easy access to all project documentation, facilitating efficient retrieval and search. This could be the project's README file or another resource like a Confluence page or Slack’s Canvas.
• Architecture Diagram: A visual representation of the system's high-level design and components, providing a clear block diagram of the infrastructure elements. Here's an example from our open-source project.
• Infrastructure Components: Overview of vital system elements, their functions, and associated costs (both fixed and dynamic).
• DB Schema (DMBL): A visual representation of the database schema showing table structure, indexes, and reference columns. It is accessible in an online editor for easy visualization. Here's an example from our open-source project.
• OpenAPI Specifications: Thorough documentation of API endpoints, methods, parameters, and responses in the OpenAPI standard. It can be viewed in an online editor for visual representation. Here's an example from our open-source project.
• Sequence Diagrams: In-depth sequence diagrams for APIs and asynchronous processes, organized using an index page. They are visually represented in an online editor and provide pseudo-code logic details. These diagrams help ensure a shared understanding and agreement before code development. Here's an example from one of our open-source projects.
• Code structure documentation: Explanation of how the codebase is organized.
• Debugging guide: In-depth reference for addressing typical concerns such as interpreting "API Error Responses," responding to alerts, conducting rapid health checks, examining application and access logs, profiling API requests and asynchronous processes, establishing connections for debugging across components like Database and Cache, and monitoring resource utilization and security.
• QA Documents:
  • Test cases doc: Catalog of test scenarios and expected outcomes for various functionalities.
  • Regression cases doc: Test cases focused on detecting regressions to ensure system stability.
  • Smoke cases doc: Essential tests performed to validate basic functionality after changes.
• Data Flow Diagram: Illustration of how data moves through the system, showing inputs, processes, and outputs.
• Postman Environments and Collections: Exported collections of API requests along with environment-specific Postman configurations. Here's an example for reference.
• Release Process: A comprehensive guide outlining the process of preparing and deploying software releases. It covers essential aspects including GitHub branch management for sprints, creating and reviewing pull requests, conducting tests on the staging environment, generating production deployment tags, and executing the steps for continuous deployment.
• Test Case Commands: Command-line directives for running individual or all test cases.
• Monitoring and Alerts: Documentation of infrastructure alert metrics with corresponding thresholds, alongside an outline of code-level alert scenarios.
• Disaster Recovery Plan: Comprehensive strategy outlining steps to recover the system in case of a disaster.
• Local Development Setup: Instructions for setting up a local development environment to work on the project.
• API Error Responses: Structure of the error response, explaining different attributes and their possible values.
• Load Testing: Guidelines and procedures for conducting load testing to assess system performance under heavy loads.
• Environment variables: List and explanations of environment variables used for configuration.