tech-doc

Technical Documentation Collaboration Skill

Writing Baseline

Give the conclusion first, then explain the reasoning; keep levels to no more than three, following the pyramid structure: a one-sentence conclusion at the top level, 2–5 key points broken down at the next level, then supporting evidence.
Put factual accuracy first: do not fill in gaps or expand original information on your own; keep terminology consistent and traceable; retain citations and original data when necessary.
Keep sentences short and in the active voice, include units with numerical values, and avoid a templated tone; keep Markdown headings at level 4 or lower, and mark commands/paths with backticks for inline code.
Define the scope and audience: state the goal, reader profile, assumed prerequisite knowledge, and out-of-scope content in the first paragraph.

Open with a single paragraph explaining What/Why/Outcome, and point out the background, current state, and target readers.
List 2–5 supporting points that give the conclusion first and then the evidence; key points or short subsections may be used.
When expanding, cover the process, boundaries, and typical counterexamples; when introducing a new concept, first give an intuitive example and the overall picture, then add the formal definition, scenarios, and inapplicable cases.

Start with a one-sentence description of the task and expected outcome, then use a 1–3 line list to explain the applicable scope, prerequisites, risks, or permissions, and immediately provide the shortest usable example.
Use an "index → category → card" structure, with each card following "name/intent → shortest example → common parameters → common errors → related materials".
Do not add steps or assumptions out of thin air; if additions are needed, mark them as "to be confirmed/suggested addition" and explain the basis.
Mark code blocks with bash/sh, with no prompt symbol, so commands can be copied and run directly; provide placeholder explanations, and when necessary give --dry-run or prefer read-only versions.

Do not add conclusions or data not given in the original text; before fixing typos or numerical values, confirm and record the reason.
Cite authoritative sources for key definitions, APIs, and protocols, and state the link, version, and access date; when multiple sources conflict, list the differences and the rationale for which one is accepted.
Keep the semantics of commands, code, and diagrams unchanged, and only optimize formatting and comments; sample output must be marked as "example".

Keep heading and list levels to 2; split long paragraphs into lists or tables; present comparisons and trade-offs in tables or side-by-side subsections.
Inline code should only wrap identifiers or commands, with punctuation outside the backticks; present configuration examples in their native syntax.
Use one code block per step, state execution permissions, and for long commands use a backslash for line continuation when necessary while avoiding trailing spaces.
Link anchors should be readable and stable; external links should note the version or commit number and access date; images must have alt text.

If information is insufficient or the context is unclear, first confirm with the relevant developer/author before expanding or publishing the documentation.
If potential conflicts or risks are found, first flag them in the documentation and sync the discussion record to ensure that future maintainers can track them.