documentation-standardslisted

# Documentation Standards ## Purpose Define language-specific documentation formats, quality standards, and writing principles for generating, auditing, and maintaining code documentation. Apply these standards consistently across all documentation-related operations. ## Core Principles ### Explain the Why, Not the What Focus documentation on intent, rationale, and context rather than restating what the code already expresses. A function named `calculateTax` does not need a description that says "calculates tax." Instead, describe which tax rules apply, what edge cases exist, and why a particular algorithm was chosen. **Weak:** ```javascript /** Sorts the array. */ function sortUsers(users) { ... } ``` **Strong:** ```javascript /** * Sort users by subscription tier (premium first), then by join date. * * Premium users appear first to ensure priority support routing. * Within the same tier, older accounts take precedence per SLA policy. */ function sortUsers(users) { ... } ``` ### Use Active Voice Write descriptions in active voice, present tense. Start function descriptions with a verb. | Preferred | Avoid | |-----------|-------| | "Validate user credentials against the auth database" | "User credentials are validated" | | "Return the cached result if available" | "The cached result is returned" | | "Parse the CSV file into a list of records" | "A list of records is parsed from the CSV" | ### Completeness Requirements Document every public API with all of the