dsh-doc

DeepSeek Harness documentation

Summary

The DeepSeek Harness documentation standard: make every page searchable, newcomer-readable, and exact enough for agents and maintainers, and keep the documentation website a tested projection of repository Markdown. Apply repository AGENTS.md files and executed gates first, then this workflow for kind-mapped metadata, progressive detail, line-aligned bilingual pages, corpus audits, and website publication. Preserve one owner per fact: source, tests, generated catalogs, package READMEs, guides, Agent Notes, and scratch each keep their own kind of truth. The session-persistence-jsonl README pair is the reference example of the format.

Table of Contents

• Workflow
• Fact-check procedure: test, do not assume
• Kind system and templates
• Voice rules
• Quality criteria
• Audit the corpus
• Wordcount budgets
• Website publication
• Detailed references
• Validation
• Dev Note

Workflow

Follow this sequence for each requested scope. Keep the common reader path brief, but do not delete failures, ownership, limitations, or other required contracts merely to reduce words.

1. Read root and more-specific AGENTS.md, the documentation standard, the target page, its source/tests, navigation owner, and bilingual record.
2. Classify the page by one primary job and reader: product quick start, user task guide, contributor tutorial, architecture overview, package/subsystem reference, generated reference, agent instruction, decision record, or scratch.
3. Place the page at its nearest owner. Keep package contracts beside package code; use docs/ for cross-package learning, user, developer, architecture, discussion, and expiring scratch material.
4. Define the reader's starting state, observable outcome, likely failure, recovery path, and next useful depth before writing details.
5. Add or revise YAML metadata — assign the kind that maps to the template for this document's job — then write Summary, Table of Contents, user-facing content, developer-facing content, optional Further Exploration, and final Dev Note in that order where the document type permits.
6. Update the bilingual counterpart in the same pass. Keep headings, lists, tables, code, links, frontmatter layout, and physical line count aligned.
7. Verify every claim against code, tests, generators, package metadata, or a current decision owner — and run the operations the page instructs, per the fact-check procedure below. Update the owner before any derivative artifact.
8. Run focused checks, then pnpm run test:docs, pnpm run doc-sync, pnpm run lint, and git diff --check; re-read the complete diff for correctness and then for brevity and repository fit.