Richard Adleta

Senior Software Architect & Full-Stack Engineer

Build Better Documentation with AI

Once upon a time, writing documentation was the part of my job that I dreaded. It was cumbersome, slow, and always felt like a chore compared to the fun parts of programming. But now, with AI and tools like Pandoc, it’s a completely different story. Documentation has transformed from a dreaded task into something exhilarating—almost as fun as writing the code itself. Markdown, AI, and smart conversion tools have supercharged my process, turning documentation from a bottleneck into a creative, seamless experience.

From Dread to Excitement: The Power of Markdown and AI

Let’s be honest: documentation used to be a grind. It was the other 20% of my job that I tolerated because I had to, not because I wanted to. But with AI stepping up, suddenly, the line between writing code and writing documentation blurred in the best way. Nowadays, English is a programming language too, and that mindset shift has made all the difference.

Markdown, with its simplicity and compatibility, became the perfect fit for making documentation manageable. When paired with AI—well, that’s when things really got exciting. AI tools don’t just help write—they collaborate. They keep my phrasing consistent, suggest better ways to explain concepts, and even help me visualize processes. Writing documentation is no longer that thing I put off—it’s become a natural extension of the development process.

Tools That Transformed the Process

Here’s how I made that transformation, step by step.

Markdown: The Foundation of Easy Documentation

When it comes to documentation, simplicity is everything. Markdown is that sweet spot between functionality and ease-of-use. It’s lightweight, intuitive, and powerful enough to handle structured documents. Here’s why I love it:

  • AI Compatibility: Tools like ChatGPT can easily parse and generate Markdown. That means my interactions with AI are frictionless—edits, summaries, or translations happen without any annoying reformatting.
  • Human-Readable: Markdown isn’t just for machines. It’s also easy on the eyes for anyone reading or writing it. Plain text, a few symbols here and there—that’s all it takes to convey structure.
  • Conversion Flexibility: With tools like Pandoc, Markdown can transform into HTML, PDF, or Word documents. Write once, publish anywhere.

Want to dive into Markdown? Check out this link for a comprehensive Markdown guide.

Supercharging Markdown Writing with VS Code Extensions

A few key tools in VS Code make working with Markdown not just productive, but enjoyable:

  • Markdownlint: Keeps my Markdown clean and consistent, suggesting corrections for common syntax issues.
  • Markdown Preview Mermaid Support: Need diagrams? Mermaid lets me visualize flows and processes right inside Markdown—perfect for explaining complicated systems.
  • GitHub Copilot: Beyond being a code assistant, Copilot helps write documentation snippets, correct typos, and even suggest better phrasing. It turns AI into an extra brain for the documentation side of things.
  • Copy Context: This one’s handy—copy entire files to the clipboard, ready to paste into AI tools for suggestions or edits.

Tip: Using extensions like Copilot helps strike the balance between thorough explanations and avoiding excessive detail.

Pandoc: Markdown’s Superpower for Conversion

Markdown is versatile, but sometimes I need a polished PDF or DOCX to share with stakeholders. Pandoc is my go-to tool for document conversion. Think of Pandoc as the Swiss Army knife for documentation—it can convert .md files into PDF, DOCX, HTML, and more.

To streamline my workflow, I created a Pandoc Shortcut script that integrates directly into Windows Explorer’s context menu. Now, with just a right-click, I can convert Markdown into any format I need. No more terminal commands, no more hassle—just quick, beautiful documentation, ready to share.

For all the gory details on setting up this shortcut, you can check out the full Pandoc Shortcut README. It covers installation, troubleshooting, and everything you need to get up and running smoothly.

Making Documentation Fun Again with AI

With AI, documentation isn’t just tolerable—it’s actually fun. I used to dread the 20% of my job that was documentation, but now with large language models, it’s more like 95% fun, and that’s because writing docs is no longer distinct from programming.

AI turns English into a programming language, and using tools like Copilot or ChatGPT, I can treat documentation like code—iterating, debugging, and improving it until it’s exactly what I want. Diagrams on-demand with mermaid, suggestions for better phrasing, and even checking tone consistency all mean that my documentation benefits from the same creativity I pour into my code.

My Workflow: From Markdown to Publication

  1. Write in VS Code: I start with Markdown, using helpful extensions to boost efficiency.
  2. AI Assistance: Utilize Copilot for instant suggestions on phrasing and structure.
  3. Quick Conversion: Use the Pandoc Shortcut to export Markdown as a polished PDF or HTML.
  4. Share & Iterate: Share drafts, get feedback, and iterate—Markdown makes rapid edits easy.

This workflow has been a game-changer. I stay in the creative zone without worrying about the tedious parts of documentation. Plus, by incorporating AI, I reduce errors and get useful suggestions without breaking my flow.

Closing Thoughts

Writing documentation used to feel like a chore, a necessary evil that kept me from doing what I truly love—coding. But now, with Markdown, AI, and Pandoc, it’s part of the fun. These tools make the whole process smooth, from ideation to a polished product.

If you haven’t already, give these tools a try and see how they can transform your workflow. And if you’re already using AI to assist with documentation, I’d love to hear your experiences—what’s worked well and what hasn’t? Drop me a message on LinkedIn or check out some of my projects on GitHub.

Let’s keep building—both the code and the documentation that inspires others to use it.

2025

Back to Top ↑

2024

Build Better Documentation with AI

4 minute read

Once upon a time, writing documentation was the part of my job that I dreaded. It was cumbersome, slow, and always felt like a chore compared to the fun part...

Back to Top ↑