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

• Cross-package references: plain.auth

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 (_prefix functions 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