documentation-guidelines

A strong README leads with a one-sentence pitch, a quickstart of at most three commands, and environment setup requirements. This skill's technical-writing reference enforces BLUF structure so readers get the answer first.

Document the endpoint and method, authentication, path/query/body parameters, a realistic JSON body example, success responses, and exact 4xx/5xx error codes. The codebase-and-api reference provides this complete template.

BLUF means Bottom Line Up Front: state the conclusion first, then supporting reasoning. For example, write 'Changed cache eviction from LRU to LFU to fix a memory leak' instead of narrating the investigation chronologically.

Yes, formal documents are produced in two complete versions: professional English and professional Chinese. The multi-language-docs reference also covers polyglot codebase patterns for Rust, Python, and TypeScript.

Diátaxis splits documentation into four types: tutorials, how-to guides, reference, and explanation. The doc-engineering reference applies it alongside Docs-as-Code pipelines using Markdown, linting, and CI-generated sites.

Comments should explain why code exists, not repeat what it does, targeting roughly one comment per ten statements. The bundled commenting modules recommend refactoring unclear code first before adding explanatory comments.