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 ...
For further actions, you may consider blocking this person and/or reporting abuse
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 :)
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.
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.
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.
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.
This maps onto something we hit on the audio-production side at AudioProducer.ai: a baked audio drama is a Word doc, and a chapter manuscript plus per-character voice assignments plus per-paragraph soundscape annotations is the markdown. Once the AI's render is opaque, you can't grep it, can't diff it line-by-line, and can't ask the model to surface inconsistencies in itself, which is exactly the Word problem you describe. Our two automation passes (Auto-Assign Voices, Auto-Assign Sounds) both keep the chapter text as the canonical source and the assignments as editable surface state, so a one-line edit regens only that scope and preserves the rest.
The Aryan-direction point about AI changing how we write artifacts (not just how fast) feels right beyond docs: once the source is AI-edit-friendly, the next thing you want is durable versioning of the prompt-and-ruleset that produced any given render. Without that, you've moved the opacity from the artifact to the agent.
Thank you for checking! 😃 Yes, I also think versioning is important. I like versioning with Markdown more than Word. We can use GitHub and easily keep history and see the differences between each version.
totally get your struggle with documentation tools. moving from Word to markdown can really streamline the process, especially when integrating AI. at Moonshift, we help you deploy a full next.js + postgres + auth build in about 7 minutes, and you keep the code on your github. if you're curious, I can set you up with a free run to see how it works.