aAAaqwq Write Product Documentation
Write from verified product behavior, not aspiration. Give each document one audience and one job, while preserving a shared fact base.
Workflow
- Freeze scope. Record product version, commit/tag, platform, deployment mode, audience, and date. Do not mix future features or another branch into current instructions.
- Build a fact matrix. Map each claim to code, configuration, test, screenshot, runtime evidence, and known limitation. Mark facts as verified, inferred, planned, or unknown.
- Choose the document role. Use a product description for value and boundaries, a full user manual for end-to-end operation, a daily guide for routine use, a technical specification for implementation, and an acceptance document for testable outcomes.
- Design the user journey. Lead from prerequisites to first success, normal operation, exceptions, recovery, data handling, and support. Explain parameters in business terms.
- Write exact side-effect semantics. State what preview/dry-run does for each operation. Distinguish “processed,” “request sent,” “artifact received,” “verified,” and “persisted.”
- Separate platforms and versions. Put Windows/macOS differences where users encounter them. Never let an old platform prerequisite leak into a new implementation.
- Use honest product language. Explain value first, but avoid unsupported detection, compliance, ROI, security, or availability guarantees. State human decision points and external dependencies.
- Create acceptance traceability. Turn every important promise into a precondition, action, expected result, evidence, and failure criterion.
- Validate the deliverable. Check links, headings, terminology, screenshots, version strings, commands, privacy, accessibility, rendering, and consistency against the fact matrix.
- Retire stale documents. Archive superseded evidence with a replacement link; do not leave multiple files claiming to be the current source of truth.
Writing rules
- Use the reader's language before internal implementation names.
- Define one term once and reuse it consistently.
- Give copyable commands only after verifying them on the scoped version.
- Keep screenshots synthetic or redacted and bind each screenshot to the documented version/platform.
- Distinguish product boundary, known limitation, expected degradation, and defect.
- Do not hide real side effects under “preview” wording.
- Keep legal/privacy/security claims aligned with the current architecture and policy review.
References
- Read document-system.md to select document types, structures, and validation gates.
- Read project-evidence.md for examples and contradictions found in this repository's documentation set.