Productivity
Confluence for Technical Documentation: Challenges and Solutions for Engineering Teams
Jun 23, 2026
•
min read
Most engineering teams have made peace with Confluence. It centralizes documentation, it's collaborative, and it gives cross-functional teams a shared space that doesn't live on any one person's laptop. Architecture decisions, runbooks, onboarding guides, incident post-mortems: all of it lives in one place, and that's genuinely valuable.
But anyone who has tried to write Confluence technical documentation has hit the same wall. The platform was built for business writing: paragraphs, tables, the occasional embedded image. The moment your documentation needs to do something more specific, like render an equation, show syntax-highlighted code that matches what's in the repository, or display a live chart, Confluence starts to show its age.
None of this means Confluence is the wrong tool. It means engineering teams end up spending time on workarounds that a better setup would eliminate. Here's where those workarounds tend to show up, and what to do instead.
Challenge 1: Adding Math and Scientific Notation to Confluence pages
Confluence has no native way to render math. The usual workarounds are screenshots of equations, attached PDFs, or typing out formulas as plain text. All three are painful to update. Change one variable in an equation and you're re-taking a screenshot, re-uploading a PDF, or hoping nobody notices the formula is now wrong.
Picture this: a machine learning engineer has just updated a loss function. Now there are three places to fix: the equation screenshot in Confluence, the PDF in the shared drive, and the plain text version someone copied into a separate doc three months ago. None of them are linked. None of them will update automatically. This is the kind of invisible overhead that compounds across a team. This poses a real challenge for engineering teams as writing math equations in confluence is a big part of the technical documentation
The Solution
LaTeX solves this because it's already the standard for technical and scientific writing. It's precise, it's plain text, and it works with version control the same way code does. The honest caveat is that LaTeX has its own syntax, and not everyone on a team will know it. If your documentation has a mixed audience of engineers, researchers, and product folks, that's worth planning for: a short style guide, a few templates for common equation types, and a reference sheet for anyone learning LaTeX for the first time go a long way.
LaTeX Math for Confluence brings this rendering directly into Confluence pages, both inline and as standalone blocks. An admin installs it once from the Atlassian Marketplace, and from there anyone on the team can write LaTeX directly in a page and see it rendered live. It doesn't change what LaTeX is, so people still need to learn the syntax, but it removes the screenshot-and-reupload cycle entirely.
Fix your Confluence documentation challenges
Discover plugins that help teams structure, simplify, and maintain technical documentation more efficiently in Confluence.
Challenge 2: Keeping Documentation in Sync with Code
Markdown is where technical documentation naturally lives: close to the code, in the same repository, reviewed the same way as a pull request. Confluence's editor doesn't work that way, and trying to force it creates a familiar problem. Confluence has one version of a doc, the repository has another, and over time they stop matching.
The Solution
The fix isn't really about tooling. It's about deciding, upfront, where each type of content lives. Confluence is good for the things that don't change often: architecture decisions, context, the “why” behind a system. The repository is better for anything that changes when the code changes. Once a team agrees on that split, a lot of the duplication and confusion goes away on its own.
When content does need to move from Confluence into a repository, Markdown Exporter for Confluence handles the conversion: pages, whole spaces, or blog posts exported to clean Markdown including images and links. It's accessible from the page menu or via a macro, so you can export a single page or an entire space depending on what you need.
Confluence-specific elements like page hierarchy, certain macros, and some advanced formatting don't always translate cleanly, so exports from heavily-formatted pages usually need a pass of manual cleanup afterward. For teams migrating documentation to a static site or syncing with GitHub, though, it removes most of the manual copy-paste work. The setup documentation covers supported elements and edge cases in detail.
Challenge 3: Adding Dynamic and Structured Content
Confluence's built-in iFrame macro is restrictive: no JavaScript, no custom CSS. For teams that want to embed a live dashboard, an interactive chart, or anything beyond static text, the iFrame macro usually can't do it, which pushes people back toward screenshots of dashboards that go stale the moment the underlying data changes.
The Solution
The better approach is to keep that content where people are already reading the documentation, rather than routing them to an external dashboard. HTML Macro for Confluence allows custom HTML, CSS, and JavaScript directly inside a page, so charts and interactive elements can stay current without leaving Confluence.
The trade-off is that this macro requires admin permissions to enable, and for good reason: it allows code to run inside Confluence pages, which is a real security consideration. Most teams will need to loop in whoever owns security policy before turning this on, and that's worth treating as a planning step rather than an afterthought.
Starting with a Solid Template
A lot of the friction in technical documentation comes from pages that were never set up consistently in the first place. One engineer writes a runbook their way, another writes one completely differently, and six months later nobody can find what they need because nothing follows a predictable structure.
A good Confluence technical documentation template doesn't need to be complicated. For most engineering teams, the essentials are: a short summary of what the document covers and who it's for, a clearly dated “last reviewed” field, ownership (who maintains this), links to related pages or the relevant repository, and a consistent section order for the content itself. That last part matters more than it sounds. When readers know where to look for the information they need, they stop avoiding the documentation.
Templates in Confluence can be set at the space level, which means new pages inherit the structure automatically. It's a small investment that pays off every time someone creates a page without having to think about how to format it.
What Good Technical Documentation in Confluence Looks Like
The teams that get this right don't try to make Confluence do everything. They write down, explicitly, what kind of content belongs where, and they revisit that decision periodically as the team and the tooling change.
Confluence Plugins help close real gaps, but they're not free. They can break after a Confluence update, they need to be kept current, and third-party plugins are an additional thing for admins to vet from a security standpoint. None of that is a reason to avoid them, but it's a reason to add them deliberately rather than all at once.
If you're trying to figure out where to start, look at where your team is currently losing the most time. Is everyone pasting equations in as images and dreading the next time one needs to change? Is the Confluence version of your API docs out of date compared to what's in the repository? Pick the one causing the most hardships, try the corresponding fix, and see how it goes before moving to the next one.
Engineering documentation in Confluence works best when the platform is treated as a foundation rather than a complete solution. It just needs a bit of help with the parts that were never really its job to begin with.
