Using AI for Software Documentation

An Assistant, not a Replacement

Artificial Intelligence¹ isn’t meant to replace the Technical Writer² – it’s here to support them in specific aspects of their work and amplify their value.

It automates repetitive tasks, centralizes lexical resources, and streamlines production, allowing Technical Writers to focus on what truly matters: clearly explaining complex concepts, designing coherent documentation architectures, and being the voice of both product designers and users. A deeply human skillset.

Every task we might consider delegating to AI can, of course, be done without it – we’ve been doing so until now. By:

• using dictionaries, glossaries, style guides
• consulting colleagues
• researching independently (which is a great way to learn)
• leveraging our knowledge and experience

... we can absolutely produce excellent documentation. The time management and task distribution may differ, but the outcome remains solid.

In fact, it’s our ability to work “without” that enables us to work “with” AI effectively, and stay in control.

AI: A Powerful Ally

The goal isn’t to have AI do the work for us, replace our role, or take over our position. It’s about empowering Technical Writers to perform better, with AI as a trusted assistant.

AI helps us think, accelerates workflows without compromising quality, and enhances output without distorting the writer’s voice.

It’s especially valuable when the Technical Writer works solo or in isolation. In that case, AI becomes a responsive teammate – ready to answer questions, review content thoroughly (without endless delays), and offer relevant feedback and suggestions.

What AI Brings to the Table

AI is undeniably a valuable asset, offering:

• Time savings on formatting, conversions, and layout tasks – while creative inspiration stays in your hands.

• Terminology consistency through instant access to glossaries and style guides.

• Proofreading support, with systematic detection of typos, inconsistencies, and lexical variations. "Systematic" is the key word here.

• Multilingual examples and code snippets, generated from specifications.

These contributions turn freed-up time into added value. You lift your head out of the whirlwind of time-consuming, tedious tasks to gain perspective and focus on what truly matters: crafting meaning, designing user experiences, and building scalable documentation architectures.

When I started out, I incorporated the "MSTP, Microsoft Manual Of Style For Technical Publications" (2nd edition—on CD-ROM, no less) into my practice.
While I’m steeped in that guide, as a human I can’t guarantee strict, systematic application of its principles. AI can.

Use Cases

API documentation is the first major use case for AI in support of Technical Writers (or developers who write their own docs). More broadly, AI can help interpret code for documentation purposes.

Of course, you must obtain permission before pasting potentially confidential code into an AI assistant. Better yet, use the same tools developers use – like Cursor, GitHub Copilot, or Claude Code.

Technical Documentation

Area	Use
API Docs	- Generate pages from OpenAPI specs - Create executable code snippets and multilingual examples - Prepare usage scenarios
Code Understanding	Analyze poorly or uncommented modules to extract intent, parameters, and usable examples I've had to document an SDK with no comments – it’s a real challenge 🧠
Diagrams & Schematics	Generate diagrams (e.g., Mermaid) from prompts, text, or code to illustrate flows and architectures.

Research & Preparation

AI can browse more sources than you can in less time. A common use case is asking it to gather and deliver information on a topic, with or without external links.

This helps you build contextual knowledge, either for self-training or to prepare for writing.
If your organization has an internal LLM, it can scan all company resources – saving you from hunting down user stories, early-stage documentation, repositories, specs, and other scattered materials.

Writing & Language Optimization

Writing – whether in your native language or in English – is central to technical communication. Strong writing is a core skill.
By "strong writing", we mean correct grammar, appropriate vocabulary, and phrasing tailored to the target audience.

That audience may vary by role (user, professional, developer) or by region, requiring knowledge of specific terminology or usage norms.

AI acts as a safety net, with access to the world’s largest library, helping you check grammar, vocabulary, punctuation, and tone. It’s the ideal assistant to verify, correct, suggest, and rephrase.

Area	Use
Language	- Rephrase, simplify, or enhance phrasing; suggest alternative vocabulary better suited to context or audience - Correct grammar, vocabulary, and typography based on language variant - Adapt terminology to context or publication channel
Content	- Suggest additions or expansions - Generate summaries, descriptions, or condensed versions - Propose (sub)titles - Provide definitions to clarify terms and avoid hallucinations (see: Writing for LLMs)
Review	- Check title capitalization, punctuation, abbreviations... - Apply a style guide (IBM's, Microsoft's or Google’s Style Guide)

Formatting & Styling

To my opinion, the choice of publication format remains the Technical Writer’s responsibility.
AI can prepare a draft version of a web page, Word document, or Markdown file – it’s ready for anything, without having an opinion.

Likewise, layout creativity should come from the Technical Writer, based on experience, graphic guidelines, stakeholder input, etc. AI can then assist with implementing parts of the design.

Tools like Canva Magic Design™ can generate beautiful layouts from prompts or documents. But they’re not always suited to technical documentation.

So: creative direction and prompt design by the Technical Writer; execution of time-consuming formatting tasks by AI.

Area	Use
Format	- Format Markdown (or AsciiDoc or RestructuredText) - Convert between formats - Transform documents (e.g., Word → Markdown)
Styles	- Create CSS - Improve CSS - Generate mobile-friendly versions
Tables	- Restructure tables (e.g., move column headers to rows) - Change table appearance and suggest styles - Generate tables from plain text

Converters between Word and Markdown have existed for years. AI’s contribution is centralizing these tools in one assistant, and tracking progress across tasks.

Review & Quality Control

As mentioned earlier, AI can be a fantastic teammate: one that reviews thoroughly, without bias or delay. You can delegate the following review tasks to AI:

Area	Use
Verify	- Check rule compliance: typography, titles, terminology - Scan for consistency within and across pages
Validate	Assess user relevance based on scenarios and context
Test	Use AI tools to test display, accessibility, and responsiveness of web documentation.

You can go further by asking AI for SEO-oriented suggestions tailored to documentation (e.g., for page headers), or to run automated checks (linting docs, testing code snippets).

Limits

AI is an assistant, not a decision-maker.
The Technical Writer must remain in control: initiating through prompts, steering via manual refinements or new iterations, and ultimately reviewing through mandatory post-editing to avoid hallucinations and tonal inconsistencies.

Therefore, AI should not be entrusted with:

• Full drafting of user documentation without product context, real-world scenarios, or user feedback.

• Generating technical examples without validation: every code snippet must be reviewed or executed.

• Regulatory, safety-critical, or legally sensitive content without expert oversight. Let’s not forget – documentation is a contractual deliverable.

The Case of User Documentation

The more functional the documentation, the less it can be delegated to AI.
User documentation is deeply contextual and requires hands-on product experience from the Technical Writer (I often say we’re beta testers) to gain the insights needed to craft realistic, user-centered scenarios.

Without:

• Context (industry, role, use cases...)
• Credible data (the actual inputs needed to get real results)
• Empathy for the end user (isn’t it our job to "step into their shoes"?)
• User feedback (from support channels and beyond)
• Writing rules aligned with your standards

The documentation risks becoming unusable – filled with outdated phrasing, irrelevant content, and missing the true goal: guiding users to get the most out of your application.
Then again, some humans have been known to produce unusable documentation too...

The Case of Hallucinations

You can help minimize AI-generated hallucinations.

• For code examples, it’s still best to consult a developer – and have them validate any language variants.

• Feed your questions to AI in small, step-by-step chunks, and stay vigilant throughout the process. Don’t take anything at face value, and always seek external validation when needed.

In short: verify, review, and stay in control. You’ve saved time on low-value tasks – now reinvest it in higher-quality oversight.

Defining Boundaries

Boundaries must be set by the Technical Writer, who should maintain full ownership of the workflow from start to finish.

They must be able to:

• Review their prompts and explain their choices;
• Identify and correct hallucinations;
• Read and understand AI-generated code;
• Reproduce similar results in new contexts (a sign that learning has occurred);
• Maintain the documentation (especially if it's a website), including sections assisted by AI.

The Technical Writer is the author of the documentation – holding both intellectual ownership and editorial responsibility.

Conclusion

To sum up: AI doesn’t replace—it amplifies.

AI enhances the operational capacity of a documentation team while reinforcing the strategic role of the Technical Writer.

AI-powered technical services coming soon

---

Notes

¹ AI or AIs (generative, conversational), depending on whether you want to be general or specific.
² Technical Writer – regardless of gender, of course.

---

© Author: Florence Venisse, STW – Initial version dated 09/26/2025