LI
Library Documentation
README structure, API reference, examples, and migration guides for library consumers
Details
Language / Topic
_UUniversal
Category
Architecture
Rules
balanced
- Write a README with: one-line description, installation command, minimal "getting started" example, and link to full API docs.
- Document every public function with parameter types, return types, thrown exceptions, and a runnable example.
- Include a getting-started example that takes the user from install to working code in under 2 minutes and 10 lines of code.
- Write migration guides for every major version. Include before/after code for every breaking change.
- Structure documentation in layers: README (quick start) -> Guide (tutorials, how-tos) -> API Reference (comprehensive details) -> Changelog (version history).
- Test all code examples in documentation by running them in CI. Untested examples rot — they break silently as the API evolves.
- Provide copy-pasteable code snippets. Every example should work as-is without modification, hidden imports, or assumed setup.
- Document error messages and what causes them. A user who encounters "InvalidConfigError" should find the explanation and fix in the docs.
- Include a FAQ or troubleshooting section covering the 5-10 most common issues reported in GitHub issues.
- Add badges to the README: build status, test coverage, bundle size, version, license. These signal project health at a glance.