Writing Issues and PRs

Whatever the platform, the writing carries the weight. Stay platform-neutral unless the user or surrounding context calls for platform-specific terms.

For starting structures by scenario (bug report, feature request, PR/MR, work item, review comment), read references/outlines.md. Those outlines are examples, not fixed templates: treat them as a starting point and shape the writing to the actual situation — reorder, drop, add, merge, or invent sections as the case demands. Prefer a repo's or tracker's own template whenever one exists.

Writing principles

• Be concise: omit needless words, cut redundancy and hedging, and prefer plain, direct prose. Make every word count. If it does not fit on one screen, it is too long.
• Be accurate, well-structured, and insightful, in a calm, natural, and human tone. Be skeptical and precise — double-check reasoning, sources, and assumptions.
• State the issue, request, or purpose clearly. Explain why it matters. Include concrete evidence.
• For English prose, follow these style guides, and apply their language-agnostic rules to prose in any language: The Elements of Style, The Sense of Style, and Chicago Manual of Style.

Formatting rules