DEV Community

shashank ms
shashank ms

Posted on

Building Technical Writing Tools with LLMs

#learnai #oxlo #ai

Technical documentation often stalls at the first draft. In this tutorial, I will build a lightweight technical writing assistant that turns rough bullet points into polished documentation, then reviews its own output for clarity and consistency. The whole thing runs against Oxlo.ai's flat per-request API, so long input context does not inflate the cost.

What you'll need

Before starting, grab the following:

Step 1: Configure the client

I initialize the OpenAI SDK to point at Oxlo.ai. I use llama-3.3-70b as the general-purpose workhorse, but Oxlo.ai also offers qwen-3-32b and kimi-k2.6 if you prefer multilingual or advanced reasoning capabilities.

import os
from openai import OpenAI

client = OpenAI(
    base_url="https://api.oxlo.ai/v1",
    api_key=os.environ["OXLO_API_KEY"]
)

Step 2: Define the system prompt

The system prompt is the only training the assistant gets. I keep it explicit about audience awareness, markdown formatting, and concise language.

SYSTEM_PROMPT = """You are a senior technical writer. Your job is to transform rough engineering notes into clean, audience-appropriate documentation.

Rules:
- Write in markdown.
- Use second person ("you") for guides, neutral voice for reference docs.
- Include a prerequisites section when setup is required.
- Keep paragraphs under 4 sentences.
- Expand acronyms on first use.
- Return only the document, no meta commentary."""

Step 3: Draft from rough notes

I create a function that takes a topic, audience, and raw bullet points, then asks the model to generate the first draft.

def draft_document(topic, audience, raw_notes):
    user_message = f"""Topic: {topic}
Audience: {audience}
Raw notes:
{raw_notes}

Write the first draft."""

    response = client.chat.completions.create(
        model="llama-3.3-70b",
        messages=[
            {"role": "system", "content": SYSTEM_PROMPT},
            {"role": "user", "content": user_message},
        ],
    )
    return response.choices[0].message.content

Step 4: Add a review layer

Drafting is only half the job. I add a second pass that checks for jargon, passive voice, and missing steps. I send the draft back to the model with a review prompt.

REVIEW_PROMPT = """You are a technical editor. Review the following documentation for:
1. Unclear instructions or missing prerequisites.
2. Passive voice that should be active.
3. Unexpanded acronyms.
4. Inconsistent formatting.

Return a revised version. If no changes are needed, return the original text."""

def review_document(draft):
    response = client.chat.completions.create(
        model="llama-3.3-70b",
        messages=[
            {"role": "system", "content": REVIEW_PROMPT},
            {"role": "user", "content": draft},
        ],
    )
    return response.choices[0].message.content

Step 5: Assemble the pipeline

I wire the two stages together so one call produces a reviewed, refined document.

def write_docs(topic, audience, raw_notes):
    draft = draft_document(topic, audience, raw_notes)
    final = review_document(draft)
    return final

if __name__ == "__main__":
    notes = """
    - new auth flow using OAuth2
    - need to register app in portal first
    - callback URL must match exactly
    - tokens expire after 1hr, use refresh token
    - SDK handles refresh automatically
    """

    doc = write_docs(
        topic="OAuth2 Authentication",
        audience="Backend developers",
        raw_notes=notes
    )
    print(doc)

Run it

Export your key and run the script.

$ export OXLO_API_KEY="sk-oxlo.ai-..."
$ python tech_writer.py

When I run this with the OAuth2 notes above, the output looks like this:

# OAuth2 Authentication

This guide walks you through configuring OAuth2 for your application.

## Prerequisites

Before you start, register your application in the developer portal. Make sure your callback URL matches exactly what you configured during registration.

## Token Lifecycle

Access tokens expire after one hour. You will receive a refresh token alongside your access token. The SDK automatically handles refresh requests, so you do not need to implement that logic yourself.

Next steps

Two concrete ways to extend this tool.

First, add a third pass that extracts API endpoints from the same notes and outputs an OpenAPI fragment. You can route that pass through deepseek-v3.2 on Oxlo.ai if you want stronger reasoning about code structure.

Second, store the final documents in a git-backed folder and add a diff step that highlights what changed between drafts. Because Oxlo.ai uses flat per-request pricing, these multi-turn review pipelines stay cheap even when you feed long log dumps or large codebases as context. See https://oxlo.ai/pricing for details.

Top comments (0)