Step-by-step DevSpeak tutorial that converts an informal stakeholder request into a formal technical specification. Covers the four translation parameters (target audience, tech context, output format, verbosity tone), the three-stage Optimize/Translate/Refine workflow, and how to verify the generated output.

Your First Translation with DevSpeak

DevSpeak converts an informal request such as "we need users to log in with Google" into a formal, audience-specific technical specification. This tutorial walks through one complete translation and explains what each control does.

What You'll Learn

  • Configure the four translation parameters that shape every output
  • Run a translation and read the generated specification
  • Refine the result without starting over

    • Prerequisites

  • A DevSpeak account (the free tier is sufficient)
  • A rough feature idea written in plain language

    • Time Estimate

    ~6 minutes

    Step 1 — Set the Four Parameters

    Every translation is shaped by four controls. They are not cosmetic: each one changes the system prompt sent to the model.

    | Control | Purpose |

    | --------------- | ------------------------------------------------------------------------------ |

    | Target Audience | Who reads the output — Junior Dev through Data Engineer |

    | Tech Context | Which domain the work sits in — Backend, Frontend, Mobile, Data/ML, DevOps |

    | Output Format | The document shape — Technical Spec, Jira Tickets, API Design, RFC, Data Model |

    | Tone | Verbosity, 0–100, with a hard behavioural split at 50 |

    The tone slider is the one people misread. Below 50 DevSpeak rewrites and tightens your input. At 50 and above it produces a full technical document with sections you did not explicitly ask for.

    Step 2 — Write the Input

    Keep it informal. That is the point.

    ``text

    We need users to be able to sign in with their Google account

    instead of making another password. Should work on mobile too.

    `

    Step 3 — Translate

    Select Senior Dev, Backend, Technical Spec, and a tone of 70. Run the translation.

    Checkpoint

    At this point you should have:

  • [ ] A generated document with numbered sections

  • [ ] Explicit acceptance criteria you did not write yourself
  • [ ] At least one edge case called out — typically account linking

    • If the output reads like a lightly edited version of your input, your tone slider is below 50. Raise it and run again.

    Step 4 — Refine Instead of Rewriting

    Refinement modifies the generated output, not your original input. Ask for a change in plain language:

    `text

    Add a section covering what happens when a user already has a

    password account with the same email address.

    ``

    Each refinement returns a complete replacement document rather than a diff, so the result stays internally consistent.

    Troubleshooting

    The output is shorter than my input

    Your tone is below 50, which puts DevSpeak in rewrite mode. Anything at or above 50 generates a full document.

    The specification targets the wrong layer

    Tech Context, not Target Audience, controls the technical domain. A Senior Dev + Frontend translation will discuss component state, not database schemas.

    Summary

    You've learned how to:

  • Configure audience, context, format, and tone

  • Generate a formal specification from informal input
  • Refine generated output without losing structure

    • Next Steps

  • Explore the other six output formats, especially Jira Tickets
  • Read the [API reference](/docs/api-reference) to automate translations