Document Review Criteria

This document describes the criteria and feedback format used when reviewing business and technical documents at Arda. Apply this process to any document being prepared for publication or team use.

Review Steps

1. Read the Document

Read the complete document before forming any judgments. Take notes on sections that are unclear or inconsistent.

2. Evaluate Against These Criteria

Clarity: Is it scannable? Does it use headers, bullets, and numbered steps where appropriate?

Tone: Professional but approachable. Not salesy, not jargon-heavy.

Readability: Target Flesch score 80+. Active voice. Short sentences.

Structure: Does it have clear sections? Are “Next Steps” or “Action Items” included where the reader would expect them?

Completeness: Are there gaps in logic, missing context, or unstated assumptions?

Conformance (technical designs only): Does the design cite the published patterns it conforms to, in a Platform Conventions section? Are the cited patterns the current ones? For each structural choice the document makes — package layout, type and file names, how the REST surface is declared, how persistence is shaped, what methods return — is it consistent with a cited pattern, or listed as a deliberate departure with a reason?

Ask for the Platform Conventions section before reviewing anything below it. A design that names no patterns is not “pattern-neutral”; it is unreviewed on this axis, and the other five criteria cannot detect the problem — a design can be perfectly clear, correctly toned, well structured, complete on its own terms, and still specify an architecture that contradicts published convention in six places.

3. Provide Feedback in This Format

• Strengths: What works well (1-2 bullets).
• Issues: Specific problems with section references (numbered list).
• Suggested Edits: Concrete rewrites for the highest-impact issues.
• Overall Assessment: One sentence summary of the document’s readiness.

4. Apply Approved Edits

If the author approves the suggested edits, apply them directly to the source file. Do not rewrite sections that were not flagged.

Notes

• Match the existing document style and tone. Impose your preferences only when they improve clarity or impact.
• Do not rewrite for the sake of rewriting.
• Flag any content that could confuse a reader if the document is customer-facing.
• For Diataxis-typed documents, verify the document stays within its declared type (see Document Writing Methodology).
• A design document is a specification someone will implement literally. Its §“Files to Create”, §“Key Classes and Interfaces”, and §“API Contract” sections are read as instructions, not as illustration. Review them at that standard — a placeholder name in a file table becomes a class name in a repository.
• When a design conflicts with a published pattern, decide which is wrong and say so. Both happen. Pattern pages are written after the fact by whoever hit the problem, so they go stale; treating them as automatically authoritative propagates the stale ones. If the pattern is wrong, the outcome of the review is a correction to the pattern, not a change to the design.
• Check the document against itself. A “minimal scope” section and a “target shape” section written at different times routinely disagree — one excluding a capability the other is built around, or a file table listing something scope explicitly defers. The implementer has to resolve that silently, and will resolve it in whichever direction the larger section points.