How I use AI to draft software docs

I’ve been using AI to draft software docs. I treat it much like an intern: I give it an assignment, provide examples, check its work, and explain what needs to change. Whether it’s AI or an intern, I have to document those lessons for the next time.

Here’s how I use AI with software docs.

Start with the user

Say I’m documenting a new security feature. I start with the person using it, often a security administrator. I assume they know security, but may not know our product.

What are they trying to do? What do they already know?

I need answers before I ask AI for a draft.

Give AI the assignment

I gather information from engineering tickets, product requirements, design documents, and conversations with developers. The sources don’t always agree. Requirements change, and some decisions are never properly recorded.

I ask AI to flag gaps and conflicts. I investigate the ones that matter.

Then I give the agent our documentation templates and style guide, along with the source material. I want a draft that fits the way we document the product, not a new format invented for every feature.

Test what AI writes

Now I try the instructions myself.

Depending on the feature, I work through the UI, call the API, or run scripts. Can I complete the task? Are the steps accurate? Did AI miss a prerequisite? Does the product behave as described?

Sometimes I find documentation errors. Sometimes I find a product issue. Sometimes testing reveals details beyond the source material.

This is where domain knowledge makes a difference.

Fix the draft – and the instructions

I make simple edits myself. There’s no reason to rewrite a prompt just to fix a UI label or cut a needless sentence.

But if AI leaves out prerequisites, I update the agent’s instructions to check for them. Then I ask for another draft and see whether the change works.

This reminds me of working with an intern, or heck with a rebellious teenager. I can explain a mistake once, but with AI I need to put that explanation in the instructions. Otherwise, I may get the same mistake in the next document.

Get an SME review

Once I’m satisfied, I send the draft to subject matter experts (SMEs) for their review.

I know the product well enough to explain the feature and challenge troublesome suggestions. SMEs make mistakes, too. I ask them to verify details I can’t confirm myself, such as unusual edge cases or implementation limits.

After that review, I make final changes and publish.

Why I use AI

AI takes on repeatable work, including copying information across documents. That saves time I can spend understanding the product and helping users.

I’m not teaching AI to do my job. I’m teaching it to handle repeatable tasks. I also use it to check my work against our complete style guide.