My Journey with AI and Documentation in Salesforce

If you work on a Salesforce team, you know that documentation is both essential and frustrating. It’s always a challenge to keep up-to-date, and no one really wants to write it. The reality is, Salesforce teams bring together a mix of coders and non-coders, and documentation has to work for everyone—not just those who are comfortable in a CLI.

AI has made documentation easier in a lot of ways. It can generate documentation quickly, summarize code, and even provide structured updates based on prompts. But there’s one (okay, actually many) problem AI hasn’t fully solved: formatting.

What is Markdown?

Markdown is a lightweight markup language designed to be easy to read and write while still being able to format text efficiently. It uses simple syntax—like # for headers, **bold** for emphasis, and - for bullet points—to create structured documents that can be converted into HTML, PDFs, or other formats. Markdown is widely used in documentation, wikis, and version control repositories like GitHub because it keeps text files clean, readable, and easy to maintain.

‍

The Formatting Struggle with AI Documentation

If you’ve ever copied AI-generated documentation into Google Docs or Confluence, you know the pain. Formatting is all over the place—bullet points don’t align, spacing is weird, and suddenly you’re spending more time fixing a document than actually using it. That’s where Markdown has been my compromise.

Markdown is structured, easy to parse, and AI-friendly. It keeps documentation uniform and predictable, which is especially useful when you have automated documentation updates tied into your Salesforce DevOps processes. But it’s not without issues.

The Tradeoff: Markdown Isn’t as Accessible for Every Role

Salesforce teams are unique in that they include people with a wide range of responsibilities. Developers are comfortable with version control, branching, and pull requests, but admins and product managers? Not so much. And that’s where Markdown presents a challenge.

While Markdown is more human-readable than most code, it’s still not as simple as clicking "Edit" in Confluence or a Google Doc. Admins and other non-coders who need to update Salesforce documentation may find it frustrating to deal with Markdown files, especially when they’re tied to version control systems like GitHub or GitLab. That extra step—learning Git workflows just to make a small documentation update—is a real blocker for many Salesforce teams.

The Best Solution I’ve Found (For Now)

Here’s where I landed:

1. Markdown keeps AI-generated documentation structured and scalable, making it easier to manage as part of a Salesforce team’s development process.
2. But it’s not ideal for admins and non-coders, since it requires some knowledge of version control to make updates.
3. Docs in Google Docs or Confluence are easier for non-coders, but AI-generated content doesn’t always translate well into those tools, leading to formatting issues and messy documentation.

This is the compromise: Markdown gives AI-generated documentation a stable, predictable format, but it’s not perfect for everyone on a Salesforce team. There’s a real need for better solutions that make documentation accessible to both coders and non-coders alike.

Why This Matters for Salesforce Teams

The biggest problem with documentation isn’t just writing it—it’s maintaining it. If documentation is too difficult to update, people won’t do it. And in Salesforce teams, where there’s often a mix of coders and non-coders working together, that gap becomes even more obvious.

Right now, Markdown is the best way I’ve found to balance structure, AI compatibility, and maintainability. But until there’s a better way to bridge the gap between technical and non-technical contributors, Salesforce teams will have to work around these limitations if they want to use AI for documentation.