Intro
I've been using AI tools such as Claude Code, Codex, and others when coding at work for more than a year. They surely speed up my coding. However, I am still writing documentation in Microsoft Word (Word) manually. So this time, I tried exploring how we can write documentation automatically using AI. Writing without Word is easier, but for now, our customers require Word, so I'll write about the Word pattern first and the non-Word pattern later.
How to Read Microsoft Word Documentation with AI?
As every developer using AI knows, using markdown (md) files is the best way to communicate with AI in May 2026. On the other hand, as far as I know, AI cannot read and write Word files directly. A Word .docx file is a zip file and contains document.xml, styles.xml, and others, so it is not suitable for AI to read directly. So it is better to convert Word files to md for AI. This time, I tried the popular document conversion tool Pandoc.
https://pandoc.org/
Using Pandoc, we can easily convert Word files into md, but detailed styles will be lost.
How to Write a Documentation Draft Markdown with AI?
A good workflow for me was as follows.
- Open the current project in an editor like VS Code and start an AI tool like Codex. This way, AI can read and refer to your existing project.
- Pass the updates to AI using md files or text. When there are images in the updates, pass screenshots to AI.
- Ask your AI to read the existing projects and existing documentation, and generate an updated draft md file. Making AI read the existing projects and documents will make the draft more similar and closer to the existing ones.
- Check the draft md file and modify it as you like.
How to Write Microsoft Word Documentation with AI?
Claude for Word was released recently.
https://support.claude.com/en/articles/14465370-use-claude-for-word
Now we can use Claude directly inside Word. There are also Excel and PowerPoint versions for Claude. I thought this would be the answer to writing documentation with AI. So I tried it full of hope.
However, there was a big problem. I could not recreate the styles with AI like in my existing documentation. AI was trying to apply the styles and said it had finished, but when I checked the documentation, I could not see the styles applied. It only applied the basic styles, but detailed styles were not applied. I also asked the AI to use Ctrl + C to copy the styles and Ctrl + V to apply them, but the AI could not do that either. In the end, AI told me to apply the detailed styles manually.🤣
There are similar tools that can use AI directly in Word, such as Gemini App and Microsoft 365 Copilot (Copilot in Word). I haven't tried them, but they seem to have the same problem and cannot apply detailed styles.
How to Convert Markdown to Microsoft Word Documentation with AI?
I also tried to generate Word files from md using Pandoc. But in this way, I could apply only simple styles. So I made a simple Python script to apply the basic settings from reference.docx and also apply detailed styles like headings, bullet points, and tables automatically. First, I had to write symbols like # (heading) and - (bullet points) in md to map them in the script. However, in this way, I need to write all the detailed style mapping code, so this time I only mapped the main styles and applied the detailed styles by hand, since this was just a test. I think we can implement all the mappings if we spend enough time on it.
How to Write Documentation Without Using Word?
Next, I tried to create documentation without thinking about Word. To give the conclusion first, I think md + HTML/CSS is the best way.
Use md for text and HTML/CSS for design. Using only md is AI-friendly and token-efficient, but it is hard for people to read because it does not have enough styling. Also, it cannot do convenient things like showing an outline on the left side. Using only HTML/CSS is easy for people to read, but it consumes more tokens for AI and is harder for people to read the code. So I thought using md for text and HTML/CSS for design is a good way to get the best of both, with token efficiency and readability for people.
The hard part might be creating the HTML/CSS template first. But once you create one with the supervision of a senior frontend developer, you can use the template repeatedly and easily. We only need to think about the text part later on. I thought of the following workflow for this plan:
- md
- Apply CSS and convert to HTML using a script with
Pandoc - HTML/CSS
It will be more convenient if we add an outline on the left side and display the main text in full size normally. Also, change to A4 size and add page breaks for print preview.
AI Avatar
Let me promote my app a little. AI Avatar is a free app that your VRoid (VRM) avatar animates through AI chat and the Enter key. Works in Chrome (Edge) and VS Code. It includes an animation editor too. I’m updating AI Avatar consistently, and a big update will come soon!
VS Code (Thank you 100+ installs!)
https://marketplace.visualstudio.com/items?itemName=web-developer-hyper.ai-avatar
Chrome (Edge)
https://chromewebstore.google.com/detail/ai-avatar/afmcfaeaaojalninahhhjnonhmlmiidi
Comments Welcome!
- Do you have any good ideas to write documentation in May 2026?
- How do you write documentation using AI now?
- What do you think documentation writing with AI will be like in the future?
Any other comments are also welcome!
Top comments (6)
In our institution, we use Confluence and Enterprise Architect. But I’m curious, why not write documentation only with HTML + CSS? AI is already very good at generating it and classic web pages are usually more readable and user-friendly.
PS: To be honest, I don’t really like writing documentation 😅
HTML + CSS is fine for small stuff but maintaining it at scale gets painful fast and AI burns through way more tokens on it too. Markdown is just cleaner to work with. If you are on React, MDX sits nicely in between, you keep markdown simplicity but can still use components where needed. Works really well in practice.
That’s true, I haven’t created much documentation directly in HTML + CSS myself. But as a consumer of external services, I’ve received a lot of documentation in HTML, and as a reader/customer I have to say it was usually very pleasant to read and easy to navigate.
For example, I once received ~100 pages of XML format documentation, and without HTML navigation and a clean structure it would have been very difficult to work with. But as you said, maintaining that manually must have been painful, especially before the AI era.
So, as both of you suggest, maybe the best approach is something in between. And for that, there are actually solutions like Jekyll, where you have a common HTML layout/index while the actual content is written in Markdown files. GitHub Pages actually uses this approach as well.
Have you looked into notion? It has ai integrations and seems to be relatively powerful for custom docs. You could probably wire up an agent and have it do some heavy lifting.
Great writeup! The md + HTML/CSS approach makes a lot of sense. Markdown stays clean and token efficient for AI while HTML and CSS handles the presentation layer nicely for readers. MDX is also worth considering if you are on a React stack since you get the best of both worlds, clean markdown that AI can work with easily plus the ability to drop in React components for richer UI when needed. I use it on my site shubhra.dev and it has been a smooth experience overall.
Try md-book!
You can write you docs in md with simple system and convert it to simple html site or pdf.