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.