tech-doc

Technical Documentation Collaboration Skill

Writing Baseline

Present the conclusion first, then explain the reasoning; keep the hierarchy to no more than three levels and follow the pyramid structure: a one-sentence conclusion at the top, 2–5 key points at the next level, then supporting evidence.
Prioritize factual accuracy: do not invent or arbitrarily extend the original information; keep terminology consistent and traceable; retain citations and original data when necessary.
Keep sentences short and in active voice, include units with numerical values, and avoid a templated tone; keep Markdown headings to level 4 or below, and mark commands/paths with inline code in backticks.
Define scope and audience: state the goal, reader profile, assumed prerequisites, and out-of-scope content in the opening paragraph.

Use a single opening paragraph to explain What/Why/Outcome, and point out the background, current state, and target audience.
List 2–5 supporting points that give the conclusion first and evidence second; bullet points or short subsections are acceptable.
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 situations where it does not apply.

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, then immediately give 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 nowhere; if supplementation is needed, mark it as “to be confirmed/suggested addition” and explain the basis.
Label code blocks bash/sh, with no prompt symbol, so commands can be copied and executed directly; provide placeholder descriptions, and when necessary give --dry-run or prefer read-only versions.

Do not add conclusions or data not given in the original text; before correcting typos or numerical values, confirm and record the reason.
Cite authoritative sources for key definitions, APIs, and protocols, and state links, versions, and access dates; when multiple sources conflict, list the differences and the reason for adopting a particular one.
Keep the semantics of commands, code, and diagrams unchanged, and only optimize formatting and comments; example outputs must be labeled “example.”

Keep headings and list levels to 2 levels, and split long paragraphs into lists or tables; present comparisons and trade-offs in tables or parallel subsections.
Use inline code only around identifiers or commands, and place punctuation outside the backticks; present configuration examples in their native syntax.
Use one code block per step, state the execution permissions, and when necessary use backslashes for line continuation in long commands while avoiding trailing spaces.
Link anchors should be readable and stable; for external links, 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 note them in the document and sync the discussion record so that subsequent maintainers can trace them.