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 (31)
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.
That's a fair point, HTML docs done well are genuinely a pleasure to read as a consumer. The Jekyll and GitHub Pages approach is a solid middle ground, you get clean markdown for content but full HTML navigation for the reader. Probably the sweet spot for larger documentation projects.
Moving to a slightly different topic, the README for Chrome extensions only allows text, so I can do almost no styling. The README for VS Code extensions is in Markdown, so I have to make two versions of the README.
So I’m thinking of creating one Markdown file with some styling (HTML or something), deploying it on GitHub Pages or something, and referring to it from both the Chrome and VS Code READMEs.
However, I’m worried that if I move the README to an external page, many people won’t brother to read it. 🤔
Thank you for your comment! 😊
I’ve never heard of Confluence or Enterprise Architect. I hope writing documents is easy for you.
I don’t like writing documentation either. I’m guessing that in the near future, all we’ll have to do is write documentation, and the rest, coding, will be done by AI.
This was actually a really interesting read because it highlights something I think a lot of us are starting to notice quietly:
AI is changing how we write documentation, not just speeding it up.
The part about separating “content” from “presentation” using md + HTML/CSS makes a lot of sense to me honestly. Markdown feels much closer to how humans and AI naturally communicate ideas, while HTML/CSS feels more like the rendering layer for humans afterward.
Also the Word styling struggle sounds painfully real 😭
Feels like we’re in this weird transition period where AI can understand structure and intent surprisingly well, but still struggles with detailed formatting consistency the moment legacy tooling gets involved.
And honestly I really like the workflow direction you’re exploring here:
AI → Markdown → Structured rendering
Feels cleaner, more reusable, and probably much easier to scale long term compared to manually fighting document formatting forever LOL.
Also huge respect for consistently experimenting instead of just theorizing about AI workflows 👀
Thank you for checking!😊
Yes, like coding, there are many ways to write documents with AI, but they are not very focused, so I wrote this post. I'm glad I could hear many new ideas from my friends, so it was worth writing this post.
By the way, I am looking forward to creating the next fun thing with you again!
Surely we'll be continuing our project but before that I need to get some things done, so as soon as I get the time I'll definitely push an update and msg you haha!
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.
Thank you for sharing your idea! 😊 I’ve been using Notion every day just for memos. I haven’t thought about integrating it with AI. Notion is quite useful because I can use it and share it on the web, so using Notion with AI also seems like a good way to write documentation easily.
Great job, man! I really enjoyed your post. My plan is to write a paragraph or an email first, then use Copilot in Microsoft Word to polish the document. I will double check everything afterward to make sure no words are missing. I haven’t tried Copilot in Excel yet!
Thank you for your messages! 😀 In my case, Claude for Word could handle only simple styles. If Copilot in Word can handle detailed styles, I would love to try it. Yes, I agree that even if we use AI for documents, it’s important to review them carefully ourselves.
It make sense. My M365 plan includes Copilot, so that’s what I’m using. Ye, I always verify the document to ensure there are no AI introduced spelling errors.
Yes, we need to verify because usually AI fixes things from wrong to right, but sometimes it changes things from right to wrong. 🤣
hahaha! It is so true :)
As someone who ships docs under tight deadlines, AI helps - but clear writing still wins. Markdown, HTML, or Word - whatever actually gets teammates reading it. Anyone else juggling tools for readability?
Thank you for checking! 😃 Yes, readability is important. In my opinion, Markdown has limited styling for readability, Word is good for readability but not very useful for AI, and HTML is good for readability but requires extra code and tokens. So using Markdown for text and HTML for styling is a good balance for readability and AI. Also, as others mentioned in the comments, Markdown + some styling (React, Vue, Rust, etc.) seems good for readability and is AI-friendly.
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.
Thank you for your reply! 😊
I’m also thinking, like you, that separating the text part and the style part is a good way to write documentation with AI.
MDX seems like a good idea. I like that it makes things easier to reuse, like React components. Especially, it looks useful when document styles get complicated.
Try md-book!
You can write you docs in md with simple system and convert it to simple html site or pdf.
Thank you for your comment! 😀 mdBook also seems good for creating documentation with AI easily. Since it’s made in Rust, it should be fast.
Interesting article, I was just recently thinking about using AI when creating documentation. I'm currently writing documentation in MD format, and Vitepress takes care of all the styling. This allows you to focus on the content while maintaining a consistent style. Then the AI will only need to write the text - even a local model will do 😁
Thank you for sharing. 😄 VitePress also looks good for styling Markdown documents with AI. Especially for developers who use Vite and Vue, VitePress looks more useful than plain HTML/CSS. Also, if we can run it locally, that’s quite budget-friendly.
Absolutely! Markdown is hands-down the "native language" for AI—it keeps tokens low and structures clean.
Wrestling with AI inside Word to apply custom styles is a losing battle. The real "developer way" is using Python with python-docx for automated template mapping, or sticking to the MD + HTML/CSS pipeline. Spot-on workflow!
Thank you for your comment! 😀 Python-docx looks good for handling Word documents with code. I would like to switch from Word to Markdown + HTML/CSS (or some other styling) if our customers allow it, for a better workflow for documentation using AI.
The Word styling problem was probably the most interesting part for me. It's funny how AI can generate pages of content but still struggle with something as simple as matching existing document styles 😄
The md + HTML/CSS approach makes a lot of sense to me as well. Thanks for sharing your experiments and workflow.
Thank you for your comment! 😊 Yes, I hope AI will get better at handling Word styles soon. Maybe it needs more training for that. But before then, we might switch to another approach, like using Markdown + HTML/CSS to write documentation more easily with AI, if possible.