README Guidelines
Each top-level package directory (e.g., plain-api/) has a README.md symlink pointing to the actual README inside the package (e.g., plain-api/plain/api/README.md). Only edit the README inside the package itself.
See plain-jobs/plain/jobs/README.md as a good example.
Purpose
The README answers: "How do I use this?" It gets users productive quickly and points them to code for deeper exploration. It is not a complete API reference.
Required Structure
Every README follows this order:
- h1 with package name
- Bold one-liner describing the package
- Table of contents with links to h2s and h3s
- Overview section with basic working examples
- Feature sections as needed
- FAQs section (second to last) using h4s for questions
- Installation section (always last)
Style
- Conversational tone: "You can..." not "The module provides..."
- First code example must be copy-paste ready with imports included
- Subsequent examples can be minimal, building on what was shown
- Link to source for advanced features:
[ClassName](./file.py#ClassName) - Cross-package references:
[plain.auth](../../plain-auth/plain/auth/README.md)
What to Document
- If users import it, document it
- Mention all public features, even advanced ones briefly, then link to code
- Internal APIs stay undocumented (
_prefixfunctions and@internalcode) - Don't fully document every parameter - mention features exist, link to code
Writing Tips
- Keep paragraphs short
- Put takeaways up front
- Use bullets and tables
- Bold important text
- Keep sentences simple and unambiguous