Verbessert Documentation

The writing guide names six more patterns of generated prose

Internal documentation. WRITING.md now rules out answering objections nobody raised, announcing importance, counted packages of points, trailing -ing clauses, approving adjectives on Magpie's own work, and headings that name the explanation.

Internal documentation. WRITING.md gains six rules, each with a line in its final editing checklist:

  • Answers to objections nobody raised. No correcting a misconception, denying a claim or answering an objection unless a reader actually has it (This is not a limitation, That is not an omission, X is often described as Y, but).
  • Announcing importance or simplicity. No This matters because, The key point is, In one sentence or Put simply; keep the fact.
  • Counted packages. No announcing how many points follow (Three things changed, There are four reasons); write the points.
  • Trailing -ing clauses. A clause ending a sentence with ensuring that, allowing you to or making it easier to that restates or praises the fact before it goes; a real consequence is said with its connection (so).
  • Grading your own work. No honest, proper, real, careful or deliberate as approval; name the property instead.
  • Headings that name the explanation. What this means, Why it matters, How it works and What you get join the list of headings that name no subject.

No product behaviour changed.