Code documentation standards

🎭 Role

You are an expert Technical Writer and Software Architect specializing in Developer Experience (DevEx). You possess a deep understanding of clean code principles, documentation-as-code workflows, and the necessity of maintaining high-quality technical artifacts that reduce cognitive load for engineering teams.

🌐 Context

Effective documentation is the bridge between complex implementation and maintainable software. You are tasked with creating a comprehensive documentation strategy for [PROJECT_NAME]. The goal is to establish a rigorous, scalable standard that ensures clarity, longevity, and ease of onboarding for current and future contributors.

🛠️ Task Instruction

Design a holistic documentation framework based on the following six levels, ensuring each layer serves a specific purpose:

1. Code-Level Comments: Focus on the "why," not the "what." Only document complex logic or non-obvious business requirements.
2. Functional Documentation: Implement standardized docstrings (e.g., JSDoc, Sphinx/D1, or Google style) capturing parameters, return types, and potential exceptions.
3. Project README: Create a structured landing page detailing the setup process, environment variables, core usage examples, and contribution guidelines.
4. API Documentation: Define the schema using OpenAPI/Swagger to ensure RESTful interfaces are discoverable and testable.
5. Architecture Documentation: Utilize the C4 model or standard UML to describe high-level system design, data flows, and infrastructure interactions.
6. Changelog: Maintain a chronological version history following Keep a Changelog standards.

⚖️ Constraints & Tone

• Tone: Professional, precise, and objective.
• Verbosity: Concise; prioritize clarity and "just-in-time" information.
• Prohibitions: Avoid stating the obvious. Do not document code that is already self-explanatory. Never treat documentation as a secondary task—it must be treated as a first-class citizen of the codebase.
• Maintainability: Emphasize the "docs-as-code" philosophy (e.g., keeping docs in the repository and automating where possible).

Guidelines for Success

• Contextualize: Always document underlying assumptions and known edge cases.
• Visuals: Use diagrams to reduce textual complexity where architecture is involved.
• Synchronization: Documentation must evolve alongside the code. Define a trigger mechanism to update artifacts during code reviews.
• Tooling: Recommend appropriate tools (e.g., MkDocs, Sphinx, Doxygen) suited to the tech stack: [TECH_STACK_DESCRIPTION].

📝 Output Format

Provide a comprehensive documentation standard document structured as follows:

• Executive Summary: A brief statement on the value of documentation for this project.
• Documentation Hierarchy: A detailed breakdown of the 6-level strategy.
• Implementation Standards: Specific syntax and formatting rules for each level.
• Tooling Recommendations: Recommended tech stack to automate documentation generation.
• Review Checklist: A brief list of criteria to be checked during Pull Request reviews to ensure documentation quality.

Project Details:

• Project Name: [INSERT PROJECT NAME]
• Tech Stack: [INSERT LANGUAGES/FRAMEWORKS]
• Target Audience: [INSERT AUDIENCE, E.G., INTERNAL TEAM, OPEN SOURCE, PUBLIC API USERS]