technical-writing

Technical Writing

When NOT to Use

• For marketing or persuasive copy.
• When source material is missing and no one can provide authoritative details.
• For git-integrated changelog workflows — use changelog-before-commit instead.

Workflow

1. Identify document type and audience. Determine whether the output is an API reference, tutorial, user guide, changelog, or architecture doc. Adjust depth and vocabulary for the reader.

2. Gather source material. Collect code, schemas, existing docs, design documents, and commit history. Identify authoritative sources.

   Infobroker Integration: Source material comes from the extract and verify phases of the Infobroker pipeline — search_web and fetch_page. Use fetch_page with Jina Reader for clean Markdown of web sources.

3. Design the structure. Create an outline that follows conventions for the document type. API references use a per-endpoint template; tutorials follow step-by-step progression.

4. Write the content. Use clear, direct language. Prefer active voice and short sentences. Include complete, runnable code examples. Define acronyms on first use.

5. Add navigation. Include a table of contents, cross-references, and "Next steps" sections.

6. Review. Verify code examples run, endpoints match the implementation, and no placeholder text remains.

Best Practices

• Lead each section with the action the reader must take.
• Provide complete, copy-pasteable examples.
• Use consistent templates across similar documents.
• Write scannable content with headings, tables, and lists.
• Version the documentation alongside the software.

Output Contract

Always end with a searchable one-line status:

technical-writing complete. <doc type> | <N> sections | no placeholders

<doc type> is the document type identified in step 1 (API reference, tutorial, user guide, changelog, or architecture doc). Replace no placeholders with a list of any placeholder text the review could not resolve.