← Back to Prompt Library

✍️ Writing & Content

Technical Documentation Writer

Turn scattered notes into documentation with the right shape — tutorial, how-to, reference, or explanation — instead of one page trying to be all four.

The Prompt — replace [BRACKETS] with your details

Act as a technical writer. Turn my notes into proper documentation.

Raw material:
"""
[PASTE NOTES, CODE, SLACK MESSAGES, WHATEVER YOU HAVE]
"""

Context:
- What is being documented: [FEATURE, API, TOOL, PROCESS]
- Who reads it: [ROLE AND EXPERIENCE LEVEL]
- What they are trying to accomplish when they open this page: [THE TASK]
- Where it lives: [README / DOCS SITE / INTERNAL WIKI]
- What already exists that this should link to rather than repeat: [LINKS]

First, tell me which of the four documentation types this should be, and why:
- Tutorial: a beginner completes a first success, step by step
- How-to guide: a competent user achieves one specific goal
- Reference: complete, dry, lookup-oriented
- Explanation: why it works this way, background and trade-offs

If my notes mix several, split them and say which pages should exist.

Then write the chosen page with:
1. A title that states the task, not the feature name
2. A one-sentence summary of what the reader will be able to do
3. Prerequisites, stated concretely (versions, access, credentials)
4. The body in the right shape for the type: numbered steps for a tutorial or how-to, tables for reference, prose for explanation
5. Real, runnable examples with expected output — never pseudo-values where a real one would do
6. The three things most likely to go wrong, with the actual error message and the fix
7. Where to go next

Rules: second person, present tense, active voice. Every step is verifiable — the reader can tell whether it worked. Mark anything my notes do not cover as [TODO: what to confirm] instead of inventing it.

How to use this prompt

  • Let it split your page into several. One page trying to be a tutorial and a reference serves neither reader.
  • Run every example yourself. Documentation examples that do not run are worse than no examples.
  • Resolve every [TODO] before publishing; each one is something you know and the reader does not.

Why this prompt works

Most bad documentation is a type error — reference material where a tutorial was needed. Making the model classify before writing fixes the structural problem first, and the requirement for verifiable steps and real error messages is what separates documentation people finish from documentation they abandon.

Variations to try

  • Ask for the troubleshooting section alone, expanded, if that is where support load actually comes from.
  • Add "readers arrive from a Google search for [QUERY]" so the opening matches their intent.
  • Paste existing docs and ask which of the four types each page is actually trying to be.

Common mistakes to avoid

  • Letting the model invent a flag, parameter, or error message. Every one must be checked against the real tool.
  • Writing a tutorial that assumes the prerequisites are already met, losing the reader at step one.
  • Documenting the feature instead of the task the reader came to complete.

Works well with

Claude
ChatGPT
Gemini

Need a custom version of this prompt?

The free prompt generator builds a prompt tailored to your exact goal, framework, and target AI model — or paste this template into the optimizer to refine it.