Published: .
Docs as Code is currently in vogue as a way of producing user documentation. It's presented as a very handy, modern approach to working and is particularly effective if you're in the software development business.
Real-world examples of the Docs-as-Code approach in action:
- Faster publishing at AWS. One AWS team moved from documenting in Word to docs-as-code and as a result saw their time from write to publish drop by 25%, and then by 50% after further optimisations.
- Massive time savings at Red Hat. Their move to docs-as-code took just 6 months and the typical developer onboarding time was clocking in at 2–4 weeks.
- Faster ramp up for new hires. Docs as code can reduce the time it takes to onboard a new dev by as much as 35%.
What are the drawbacks of this approach? Is Docs as Code actually required for help systems, or is it just a useful tool for writing technical specs and API documentation? That's the question this article sets out to answer. We'll look at what Docs as Code is, when it's appropriate to use it and ultimately you'll be in a position to decide for yourself whether you should make the switch or continue to develop your help system in the traditional way. The points we'll cover are:
- Docs as Code vs. DITA
- What is Docs as Code in the context of writing help systems?
- Advantages and disadvantages
- Who is Docs as Code a good fit for?
- What alternatives exist to this methodology?
- Hybrid approaches
- Final recommendation
Docs as Code vs DITA: sorting out a common confusion
Before we go any further on Docs as Code, it's worth clarifying one common point of confusion: the relationship (and indeed the difference) between Docs as Code and DITA (Darwin Information Typing Architecture). A lot of people think of them as alternatives to each other. They're not. They're on completely different levels and can in fact work together.
The fundamental difference: workflow versus architecture.
Think of it this way:
- Docs as Code is a workflow. It's the answer to the question of 'how do we write, review and publish our documentation as part of the SDLC?' The four pillars are plain text, version control (Git), pull request reviews and CI/CD.
- DITA is an information architecture standard. It's the answer to the question of how do we structure, reuse and version content at scale? It defines a very strict set of rules around topics, maps, profiling (conditional processing) and content reuse (conref, keyref).
To use an analogy: Docs as Code is about the factory assembly line (the workflow), DITA is about the blueprint and the modular parts (the content architecture). You can have one or the other, or both.
Where the confusion comes from
The confusion arises because both approaches often share two visible traits:
- They prefer plain text to binary formats. DITA uses XML (typically .dita files) and Docs as Code tends to use Markdown or AsciiDoc. Both of these are human readable and version control friendly.
- They enable single sourcing - you can generate multiple outputs (HTML, PDF, CHM) from a single source.
However the complexity and the philosophy are very different.
Key differences at a glance
| Aspect | Docs as Code (typical) | DITA |
|---|---|---|
| Underlying format | Lightweight markup (Markdown, AsciiDoc, reStructuredText) | Strict XML (with predefined elements: <task>, <concept>, <reference>) |
| Learning curve for writers | Moderate — Markdown takes hours, Git and CI/CD take weeks | Steep — understanding topic types, maps, conditional attributes, and tooling takes months |
| Content reuse model | Basic — includes and transclusions (e.g., `!include`), limited variables | Advanced — conref (reuse by reference), keyref (indirect linking), conditional filtering by product/audience |
| Tooling ecosystem | Lightweight generators (MkDocs, Docusaurus, Sphinx, Antora) + CI pipelines | Heavyweight XML editors (Oxygen XML Editor, XMetaL, SDL Contenta) or CCMS (Tridion Docs, Ixiasoft) |
| Typical output formats | HTML (web-first), PDF (via plugins, often with complex setup), CHM (very rare) | PDF (highly polished), HTML5, CHM, Microsoft Help, and even printed manuals out of the box |
| Target audience for the approach | Developer-led teams, startups, open source projects, API documentation | Large enterprises, regulated industries (aerospace, medical, defense), global publishing with heavy reuse |
| Typical project scale | Small to very large (e.g., Kubernetes docs use MkDocs with custom tooling) | Medium to massive (thousands of topics, dozens of product variants, multiple languages) |
Can you use DITA with Docs as Code?
Yes absolutely, they're not mutually exclusive at all. You can absolutely have the Docs as Code workflow and still be using DITA as your content architecture. Here's what that would look like in practice:
- You store `.dita` and `.ditamap` files in a Git repository.
- You write and edit them using an XML editor (or even a plain text editor if you're brave).
- You use pull requests for peer review and change tracking.
- You set up a CI/CD pipeline that runs a DITA Open Toolkit (DITA-OT) build to generate HTML, PDF, or CHM automatically.
- You deploy the output to a web server or package it with your app.
This is actually a fairly common combination in mature organisations. Take a large tech company with a huge requirement for reuse (IBM, Oracle come to mind) for example. They'll typically use DITA as their authoring standard, but will have moved to Git + CI/CD for their collaboration and automation. In that case DITA provides the semantics and the conditional logic and Docs as Code provides the modern developer workflow.
When would you go for DITA rather than Docs as Code (or the other way around)?
Here is practical guidance:
- Choose DITA (with or without Docs as Code workflow) if:
- You need to reuse content a lot. The same paragraph, warning, or step shows up in many products or for different audiences.
- You're in a regulated sector which demands audit trails and standardised content types (e.g. safety warnings must be tagged as <warning>).
- You generate documentation for a range of product variants (Professional, Enterprise, Ultimate etc.) from a single source using conditional filtering.
- You already have a team of technical writers with XML training.
- Choose Docs as Code (with lightweight markup) if:
- You want developers to contribute to the docs without them having to learn some complex XML schema.
- Your documentation is predominantly narrative, tutorial style or API reference (where Markdown is of course the ideal format).
- You care more about speed of setup and speed of deployment than you do about architectural purity.
- You're publishing primarily to the web (HTML) with PDF being a secondary output.
A note on AsciiDoc
If you're in the position of having to choose between the simplicity of Markdown (Docs as Code) and the semantic power of DITA then take a look at AsciiDoc. AsciiDoc is a light weight markup language which supports a lot of the DITA-like features: cross references, conditional content (profiling), include directives and even basic content reuse. Tools like Antora (which uses AsciiDoc) are often described as "Docs as Code with DITA-like capabilities". It's not a full DITA replacement in the enterprise world, but it does a heck of a lot more than you'd expect.
The bottom line
Don't confuse Docs as Code with DITA. They answer entirely different questions. Docs as Code is about how you work together and how you publish. DITA is about how you structure and reuse content. You can go with either, both or neither depending on your team size, your industry and the complexity of your content. In fact some of the most sophisticated documentation systems in the world use DITA + Git + CI/CD to bring together the best of both worlds.
What Is Docs as Code?
In simple terms Docs as Code is about moving away from the traditional office editor (Word, Google Docs) and the visual tools (like Confluence) and towards a single system where documentation is as much a part of the project as the code itself. Rather than having huge DOCX files or a closed system, you're writing your documentation in plain text files using a light weight markup language (Markdown being the most popular, AsciiDoc and reStructuredText being the others).
The files are stored in a VCS (usually Git) alongside the code. When it's time to publish they get turned into a proper website (HTML), a PDF or whatever the required output format is via the CI/CD tools. Sounds complex, doesn't really be.
Comparing Approaches to Creating User Documentation
| Criteria | Desktop application | SaaS platform | Docs as Code approach |
|---|---|---|---|
| Typical examples | MadCap Flare, Adobe RoboHelp, HelpNDoc, Dr.Explain | ClickHelp, Document360, HelpJuice, GitBook | MkDocs, Docusaurus, Sphinx, Antora |
| Markup language | Visual editor (WYSIWYG), occasionally XML/DITA | Visual editor (WYSIWYG) | Text-based (Markdown, reStructuredText, AsciiDoc) |
| Storage & version control | Proprietary binary or XML projects, limited Git integration | Vendor cloud, change history exists but version control is limited | Files in Git. Full history, branches, pull requests |
| Collaboration | Weak (via shared network folders) | Strong. Comments, notifications, real-time co-editing | Strong (via PR). Transparency, code review, automated checks |
| CI/CD integration | None | None | Full. Automated builds, link checking, deployment |
| Primary output formats | HTML, PDF, DOCX, CHM, ePub | HTML, PDF, DOCX | HTML |
| Key strengths | Powerful tools for complex print output, CHM | Easy to start, browser-based, built-in analytics | Transparency, automation, unified workflow with development |
| Key weaknesses | High cost, complexity, tied to a desktop | Less control over data, challenges with CHM and complex PDFs | Requires technical skills (Git, CI/CD), not suitable for CHM |
Core principles of Docs as Code
The Docs as Code approach rests on four pillars:
- Plain text formats. Markdown (or similar) only — this ensures lightness, transparency and compatibility.
- Version control (Git) so every change is recorded. You can always view the edit history, compare versions and roll back a bad change if required.
- Review via Pull Request (PR). Documentation changes are subject to the same review process as code. A dev will add a new feature and propose the associated documentation changes via a Pull Request. Colleagues will comment on the PR and once it's approved the changes are merged into the main branch.
- Automated building and publishing. The moment changes are accepted the CI/CD system will automatically rebuild the documentation and publish it to the site. No manual 'Export' button required.
Let's look at a practical example.
Imagine a team building an app called FitTracker and a very effective manager decides to go down the Docs as Code route for their help documentation. Here's a typical day's work with that in place:
- Developer Ted adds in a new feature (real time heart rate tracking).
- Documentation is created and reviewed like code:
- Ted creates a new branch in Git for his task.
- Inside the /docs folder of the repository, he finds the pulse-monitoring.md file and updates it, describing the new feature in plain language using Markdown.
- He then creates a Pull Request (PR) to merge his changes into the main branch. Both the developer and the technical writer participate in this PR.
- Technical writer Maria reviews the PR. She sees exactly which lines Ted changed and leaves a comment: "Great description, Ted! Could you please also add a screenshot of what this looks like in the UI?"
- Ted adds a screenshot, commits it to the same branch, and Maria approves the PR. The changes are merged into the main branch.
- Automated publishing. As soon as the PR is merged, a configured CI/CD pipeline (for example, GitHub Actions) runs automatically. It takes all the Markdown files from the repository, builds them into an HTML website, and deploys it to the server hosting the app's online help.
- Users see the result. For instance, user Sarah opens the app, notices the new feature, and goes to the "Help" section (which is that very HTML site) — and sees up-to-date documentation with screenshots.
As you can see, the approach of Docs as Code not only makes the life of technical writers easier but also ensures the documentation's liveliness and close ties with the product. You should also bear in mind that it all depends on the team's documentation culture in the first place.
Popular tools include MkDocs, Docusaurus, Sphinx, Antora, hosting providers like Read the Docs, GitHub Pages, and Netlify.

An example of the Docs-as-Code approach in action is this article from Squarespace engineers: Making Documentation Simpler and Practical: Our Docs-as-Code Journey: Our Docs-as-Code Journey. Although it's not about the documentation of end users, but developers, they have migrated their documentation into code repositories instead of external wikis (Confluence). This has allowed them to address several critical points:
- Sync with code: changes to functionality and their descriptions are in the same Pull Request. You can no longer change the code and forget about the documentation.
- Unified workflow: developers do not need to switch between writing documentation and coding — their IDE is the place to work on both code and text.
- Quality: documentation passes peer reviews, thus virtually eliminating factual errors.
- Versioning: it's easy to see what the documentation looked like six months ago for a particular version of the service.
- Automation: linters can catch broken links, formatting issues, and even discriminatory phrases.
Squarespace also highlights some of the challenges they've faced while embracing Docs as Code:
- Entry barrier for non-engineers: if a product manager, designer, or technical writer has no experience with Git and Markdown, they need to learn these things to make documentation changes.
- Discovery is harder: if documentation is split into hundreds of repositories, a search requires extra aggregation to build a unified "knowledge portal."
- Infrastructure: now the team should also maintain the documentation publishing infrastructure.
Advantages and disadvantages of the Docs as Code approach
Pros
- Full versioning and transparency: every change is visible and traceable. You can revert to any previous version of the documentation. This is especially important if you ship documentation together with your product and need to match particular versions of the software.
- Integration with development: developers can edit documentation in the same pull requests and pass code reviews. This reduces the barrier to contribution.
- Automated publishing: once changes are merged and passed the CI/CD pipeline, the documentation is automatically published to a website. Perfect for agile development.
- Design flexibility: the look and feel of your online help can be customized down to the last pixel using modern front-end technologies.
- Tools are free: most tools are open source, and hosting documentation as a static website is often free for open-source projects or small teams.
Cons
- High barrier for technical writers: learning Git, the command line, Markdown, and CI/CD is time-consuming and distracts them from actual writing. Many experienced technical writers who prefer visual tools (not plain text) will struggle.
- Lack of tools for multimedia and screenshots: user guides often contain dozens or hundreds of annotated screenshots. Docs as Code has no built-in tools for automatically numbering UI elements, capturing windows, or updating images. Everything should be done manually or with external tools, which is extremely time-consuming.
- No support for popular formats: you'll get a great-looking website, but generating CHM (standard for Windows embedded help) is close to impossible, and PDF requires complex setup. For many software products, this is a deal-breaker.
- No support for non-text content: long tables, rich formatting, embedded videos — everything requires extra effort and plugins.
- Infrastructure: to host documentation, you need CI/CD pipelines that require maintenance. In small teams, this falls to developers or tech writers, which is a distraction from their main job.

Search and analytics in Docs as Code: the hidden complexity
One of the big silent showstoppers when it comes to Docs as Code (and rarely mentioned in enthusiastic blog posts about the approach) is the question of search and analytics. Help authoring tools (HATs), such as MadCap Flare, Dr.Explain, or ClickHelp, have built-in search engines and analytics dashboards. When using them, you can publish your documentation, and the search will "just work." You can see what your users are searching for, what they find and don't find, and optimize your documentation.
On the other hand, Docs as Code offer no search and analytics out of the box, and the reasons for this limitation are far from obvious.
The core problem: static sites are, well, static
The site generated with a static site generator (SSG) such as MkDocs, Docusaurus, or Sphinx is a collection of HTML, CSS, and JavaScript files that reside on a web server. There is no database or application server involved. This approach is good for performance, security, and simplicity but comes with some limitations.
For example, it is impossible to implement server-side search, since there is no server to begin with. You need to implement search either on the client side (in the browser) or use a third-party search API.
Client-side search means that when a user hits "Search," their browser downloads a file with the search index (typically in JSON format) that contains information about all the pages. Then, some JavaScript code parses this index on the client side and returns the search results. It's blazingly fast but has some caveats we'll discuss below.
How search works in pure Docs as Code
Most static site generators have a built-in solution for client-side search. These solutions typically work as follows:
- At build time, the SSG creates a search index — a JSON file with all the information needed for search: titles, URLs, headings of the pages, and sometimes the body text itself.
- The user's browser downloads this file when they first open the search box.
- Some JavaScript code instantiates the search index and highlights the relevant search terms.
- No search analytics are available out of the box.
Some popular built-in or out-of-the-box solutions are:
- MkDocs has a built-in search (powered by lunr.js) that works offline but provides no relevance scoring.
- Docusaurus provides Algolia DocSearch (free for open source, paid for private projects) or local search plugin.
- Sphinx has an HTML search engine built into its documentation.
- Antora has no built-in search; you need to set it up with a third-party search engine (Algolia, Swiftype, or your own server).
The limitations of client-side search (crucial for user documentation)
Client-side search is entirely adequate for documentation that is used internally by the development team or for open source projects with a few dozen pages of documentation. However, for external customer-facing documentation, these approaches are insufficient or, at best, uncomfortable for the end-users. Here are a few reasons:
| Limitation | Why it matters for user documentation |
|---|---|
| Large index files (e.g., 3–10 MB of JSON) | Users on mobile or slow connections experience delayed search or timeouts. Support teams then receive complaints that "search is broken." Even on fast connections, a 5 MB download feels sluggish compared to instant server responses. |
| No typo tolerance (basic substring matching) | If a user types "documenation" instead of "documentation," client-side search often returns nothing. Server-side engines (like Elasticsearch) automatically handle typos and stemming. Your users will blame your help system, not their typing. |
| No relevance ranking (no TF-IDF or BM25) | Client-side search typically shows results in alphabetical order or by simple keyword count. A page where the term appears once in the title might be ranked below a page where it appears ten times in a footer. Users do not understand why search "doesn't work." |
| No search analytics (what users search for) | You cannot see what terms users are typing. Without this data, you do not know where your documentation is failing. Are users searching for "invoice" but finding nothing? Is "how to reset password" a top query? You remain blind. |
| No advanced features (filters, facets, synonyms) | Users cannot filter results by product version, topic type (troubleshooting vs. tutorial), or audience. Synonyms ("log in" vs. "sign in" vs. "authenticate") cannot be configured. In enterprise products, this is a major usability gap. |
Solving search in Docs as Code: the third-party path
To achieve the level of search quality provided by commercial HATs like MadCap Flare or Dr.Explain, you'll need to turn to a third-party search API. The most popular options in 2026 are:
- Algolia DocSearch — free for open source documentation, paid for commercial projects (around $49–99/month). Offers typo tolerance, relevancy scoring, analytics, and instant results. Used by Docusaurus, Vue.js docs, React docs, and thousands of others.
- Meilisearch — open-source, can be self-hosted or used as a cloud service. It offers typo tolerance, filters, and analytics. Self-hosting requires a server (even a small one).
- Typesense — similar to Meilisearch, fast typo-tolerant search. Cloud or self-hosted.
- Google Programmable Search Engine — free tier (with ads) or paid. Less flexible but easy to set up. Ads on search results may look unprofessional for enterprise documentation.
- Swiftype (Elastic App Search) — more enterprisey, more expensive. Designed for large documentation portals.
The catch: you must set up and configure the search engine yourself. To integrate a third-party search engine into your Docs as Code documentation, you'll need to:
- Sign up at the provider's website and obtain API keys.
- Add JavaScript code for the search client to your static website (typically by modifying your HTML or JavaScript files).
- Set up a crawler or indexing job that will run on each documentation build and submit new or changed content to the search engine.
- Monitor your usage to stay within the limits (e.g., 10,000 search operations per month for Algolia's free tier).
None of this is impossible, but it certainly takes time and effort. In a HAT like Dr.Explain, you simply check a box, and search becomes available.
The analytics problem: what are users actually doing?
The search analytics are only part of the story; the other part is general analytics — what users are doing on your documentation portal. Traditional HATs often have built-in dashboards that show:
- Most viewed pages
- Zero-result searches (critical for content optimization)
- Time spent on a page, bounce rates, and page navigation (where users go after each page)
- Bounce rates
- Navigation paths (where users go after each page)
With Docs as Code, you have none of the above by default. You can add Google Analytics, Plausible, or Umami, but they will only give page views — not documentation-specific metrics.
Building your own analytics stack (if you must)
If you need documentation-specific analytics in a Docs as Code setup, here is what a custom solution looks like:
- Track search queries: log all queries submitted to your search API (Algolia, Meilisearch, etc.) to a database or analytics platform (e.g., Segment, Snowplow).
- Track zero-result searches: monitor when the search engine returns no results. This is the most valuable metric for identifying documentation gaps.
- Track page navigation: use a product analytics tool (PostHog, Mixpanel, Amplitude) to build funnels — e.g., "Home → Installation → Troubleshooting."
- Track search-to-click conversion: log which search results users click on to see if your search ranking is working.
- Build a dashboard: connect all these data sources to a BI tool (Metabase, Superset, or even Google Sheets).
This is possible, but it requires a data engineer or a very determined technical writer with analytics skills. Most documentation teams do not have this luxury.
When this actually matters (and when it doesn't)
Not every documentation project needs sophisticated search and analytics. Here is a practical guide:
You can live with client-side search if:
- Your documentation has fewer than 100 pages (the search index file will be small).
- Your users are developers or technically proficient (they are willing to tolerate basic search).
- You have no budget for third-party services.
- Search is a secondary feature (users will navigate with menus and links).
You need professional search + analytics if:
- Your user documentation targets non-technical end-users (accountants, HR managers, small business owners). They expect Google-like search and will not be patient with poor search experiences.
- Your documentation has hundreds or thousands of pages. Client-side search becomes unusably slow.
- Your support team is overwhelmed, and you need to optimize documentation based on search analytics.
- You are accountable for documentation ROI (e.g., reducing support tickets). Without analytics, you cannot measure success.
- You support multiple product versions, and users need to filter search results by version.
A concrete comparison: Dr.Explain vs. pure Docs as Code (search & analytics)
To bring things to life, let's take a look at how a traditional HAT (Dr.Explain) compares to a Docs as Code setup (MkDocs, no third-party services) in terms of search and analytics:
| Feature | Dr.Explain (Desktop HAT) | Pure Docs as Code (e.g., MkDocs) |
|---|---|---|
| Built-in search | Yes. Works immediately after build. No configuration. | Yes (client-side, lunr.js). Works offline but has limitations (large indexes, no typo tolerance, no relevance ranking). |
| Typo tolerance | Yes (configurable). | No. User must type exact terms. |
| Search analytics (what users search for) | No (unless you publish to a web server with logging). Dr.Explain generates static HTML, so you would need external analytics. | No by default. Requires external analytics setup (Google Analytics, Plausible, etc.). |
| Zero-result search tracking | Not built-in. Would require custom logging. | Not built-in. Would require custom logging plus search service integration. |
| Page view analytics | No built-in. Add Google Analytics manually. | No built-in. Add Google Analytics manually. |
| Documentation-specific dashboards (top searches, failed searches, popular pages) | No. You build yourself or use third-party. | No. You build yourself or use third-party. |
The table shows an interesting truth: neither Dr.Explain nor pure Docs as Code provide built-in search analytics or documentation dashboards out of the box. ClickHelp and MadCap Central (the cloud versions) do.
This means that the analytics gap is not unique to Docs as Code; it is a characteristic of any static HTML documentation (whether generated by a HAT or a static site generator). The difference is that Docs as Code proponents rarely mention this, while HAT vendors are much more transparent about it.
Do not ignore this section if you're thinking about Docs as Code for your user documentation
If you are considering Docs as Code for your user documentation, do not skip the search and analytics discussion. Ask these questions before making the decision:
- How big will our documentation grow in 12 months? (If it will be over 200 pages, client-side search will struggle.)
- Who are our users? (Non-technical users need typo tolerance and relevance ranking.)
- What is our budget for third-party search services? (Algolia, Meilisearch Cloud, etc.)
- Who will maintain the search and analytics stack? (Is there a developer on the team who can debug indexing issues?)
- Do we need to know what users search for and fail to find? (If yes, you need search analytics — which is not free or automatic.)
For many teams, the answer will be: "We are fine with basic search and we will add Google Analytics for page views." This is a valid choice, but it is an informed choice.
If you need professional search without the maintenance, a hybrid approach (GitBook, Read the Docs with built-in search, or a cloud HAT like ClickHelp) may be a better fit.
The bottom line
Search and analytics are not impossible in Docs as Code; they are just not automatic. You must architect them, pay for them (in time or money), and maintain them. For API documentation or internalwikis, basic client-side search is often sufficient. For user-facing documentation targeting non-technical audiences, professional search is a requirement — and that requirement has a cost and complexity.
Factor this into your decision-making. A tool that gives you search "for free" (like a cloud HAT or a hybrid CMS) may be cheaper in total cost of ownership than a free static site generator plus a paid search subscription plus the engineering time to integrate and maintain it.
Who is Docs as Code a good fit for (when writing help documentation)?
Despite the drawbacks listed above, there are scenarios where Docs as Code fits perfectly.
- Teams where documentation is primarily written by developers: if you don't have dedicated technical writers and developers already know Git and Markdown, Docs as Code lets them write documentation without context-switching.
- API documentation and technical specs: for documenting APIs, SDKs, and libraries, Docs as Code has become the de facto standard.
- Open source projects: the community is used to pull requests, and docs-as-code allows external contributors to submit documentation changes easily.
- Products where help content is delivered only as a website: if you don't need CHM, PDF, or embedded help, Docs as Code gives you a modern website with good search.
Who is Docs as Code NOT a good fit for (when writing user documentation)?
Here are typical situations where Docs as Code will create more problems than benefits.
- Your team has technical writers with no development background: they spend time learning Git and CI/CD instead of focusing on content quality. This harms productivity and increases frustration.
- Your user documentation contains hundreds of annotated screenshots: manual screenshot handling in Docs as Code is a time sink. Every UI update forces you to redo many images.
- Your product ships with embedded CHM help or requires context‑sensitive help (F1): Docs as Code cannot generate quality CHM files or support context IDs. For Windows applications, this is practically a non‑starter.
- Your user manual needs to be published in multiple formats (CHM, PDF, HTML, DOCX): getting all of these from a single Docs as Code source with acceptable quality is very difficult. You end up maintaining multiple pipelines.
- You have a small budget for infrastructure and training: adopting Docs as Code requires time to set up CI/CD, train people, and sometimes even hire a DevOps engineer.
What alternatives exist to the Docs as Code methodology?
If you recognize yourself in any of those points, don't despair. The methodology might feel like overkill — and fortunately, there are excellent alternatives specifically designed for creating user guides. They combine the convenience of visual editing, automation of routine tasks, and support for popular formats.
Examples include tools like HelpNDoc, MadCap Flare, and ClickHelp. Another alternative is Dr.Explain — a solid choice if MS Word no longer works for you but Docs as Code feels too bulky and complex.
Why Dr.Explain might be the optimal choice for writing user help?
Dr.Explain is a desktop application for Windows, purpose‑built for developing help systems in multiple formats: HTML (no special knowledge required), PDF, DOCX, and CHM files. It addresses the pain points of the Docs as Code approach that reduce efficiency for authors without a technical background.
Key features:
- Zero barrier to entry: Dr.Explain's interface is intuitive to anyone who has used Word or Google Docs. You start creating documentation right after installation — no Git, no Markdown, no CI/CD.
- Automated screenshot annotation: the built‑in screen capture tool recognizes UI elements, numbers them, and creates captions. When the UI changes, you simply replace the screenshot — all annotations stay in place. This saves hours of work per release.
- Popular formats from a single source: from one Dr.Explain project, you can export CHM (embedded help), responsive online help (HTML), PDF, and DOCX in a few clicks.
- Context‑sensitive help for applications: Dr.Explain supports Help Context IDs, allowing you to map F1 help calls to specific windows and dialogs in your Windows application. This is something Docs as Code fundamentally cannot do.
- Collaboration: multiple authors can work on a project via a shared folder or collaboration server with section locking and comments. No merge conflicts, no CI setup.
Of course, Dr.Explain doesn't try to replace Docs as Code where the latter truly shines. If your help system is essentially technical documentation for developers (APIs, SDKs), if it doesn't contain complex screenshots and doesn't require CHM, and if everyone on the team already knows Git — then Docs as Code remains a great choice. But if your goal is to quickly create and easily maintain high‑quality user guides with lots of illustrations, publish them as CHM, PDF, and online, without spending time on infrastructure and tool training — Dr.Explain gives you all of that out of the box.
Hybrid Approaches: when the lines blur
The previous sections presented a clear binary choice: traditional desktop HAT tools (like MadCap Flare or Dr.Explain) versus Docs as Code (Markdown + Git + CI/CD). In reality, the modern documentation landscape is far more nuanced. Many teams and tools occupy the middle ground, blending the simplicity of visual editing with the power of Git-based workflows.
These hybrid approaches are often the most practical choice for teams that want the best of both worlds — without fully committing to the extremes of either end.
Why hybrid exists?
Pure Docs as Code works beautifully for developer-centric teams. But it creates friction when:
- Tech writers are comfortable with WYSIWYG editors but need version control.
- Subject matter experts (SMEs) need to contribute occasionally but won't learn Git.
- The team wants automated publishing but also needs rich media handling (screenshots, callouts, embedded video).
- Management wants the transparency of pull requests but cannot afford a months-long migration.
Hybrid approaches solve these friction points by meeting teams where they already are
Four common hybrid models
Hybrid approaches exist in many flavors (GitBook is probably the most successful in 2026). I have categorized the most popular approaches from "Docs as Code with training wheels" to "Traditional tool with Git lipstick":
| Model | How it works | Best for |
|---|---|---|
| 1. Git-backed WYSIWYG editor (e.g., GitBook, Read the Docs, HackMD) | A web-based visual editor that automatically commits changes to a Git repository. Writers never see Git, but developers can clone, branch, and PR from the same repo. | Teams where writers want a Notion-like experience, but developers demand Git history and automation. |
| 2. Static site CMS with Git backend (e.g., Netlify CMS, Decap CMS, TinaCMS) | A web UI for editing Markdown files stored in Git. The CMS handles commits and pull requests behind the scenes. Writers edit in a familiar form, and the site rebuilds on merge. | Content teams that need structured editing (dropdowns for categories, image uploads) but want to keep the Docs as Code output stack. |
| 3. Traditional HAT with Git integration (e.g., MadCap Flare + Git, ClickHelp + Git sync, Paligo) | The desktop or cloud tool still provides visual editing and binary-friendly features (screenshot annotations, CHM generation), but the source files are stored in Git. Teams can do branch-based workflows and peer reviews, though diffing binary files is limited. | Large documentation teams that cannot abandon legacy features (CHM, F1 help, complex PDF) but want modern version control and CI/CD. |
| 4. Markdown in a CMS with visual preview (e.g., Contentful + Gatsby, Sanity + Next.js) | Writers fill out structured forms (title, body, tags). The body field accepts Markdown or a rich text editor. Content is stored in a headless CMS but rendered through a Docs as Code static site generator. | Teams that need separation of concerns: marketing manages content in CMS, developers manage templates in code. Suitable for large organizations with dedicated roles. |
Real-world example: GitBook
GitBook is the most successful hybrid tool in 2026: here's how it bridges the gap:
- For technical writers: block-based visual editor, similar to Notion/Confluence, with ability to embed images, tables, code, and interactive diagrams (no markdown needed)
- For developers: all the docs are in a git repo (GitHub, GitLab, Bitbucket); changes made in visual editor become git commits; developers can clone the repo, edit in their IDE, and push changes
- For CI/CD: GitBook provides native API/Webhook hooks — changes merged to master can trigger external CI/CD pipelines (e.g., to export to PDF)
- For reviewers: GitHub/GitLab PRs are natively supported; writers can propose changes, and reviewers see the visual diff inline
GitBook sacrifices flexibility for the sake of productivity: compared to a hand-rolled Docusaurus site, its HTML templating is less flexible (you'll have to hack around if you want to change the default template). On the other hand, most teams would rather have a hybrid block-based editor than spend months migrating to a new tooling stackAnother hybrid example: ClickHelp with Git Sync
Another hybrid example: ClickHelp with Git Sync
ClickHelp is traditionally a SaaS help authoring tool with WYSIWYG editor; in 2024 they introduced two-way Git synchronization, enabling this hybrid workflow:
- Writers keep using their beloved WYSIWYG editor (to annotate screenshots, build tables, manage conditional content, etc).
- But all the topics are stored as markdown/html files in a git repo (on GitHub, Azure DevOps, etc.)
- Developers can clone the repo, edit topics in VS Code, and push changes; ClickHelp detects the push and rebuilds the corresponding topics.
- PRs can be used to build the help system; they can be deployed to ClickHelp's cloud or to an external server.
ClickHelp preserves the strengths of traditional tools (annotation of screenshots, exporting to CHM) while getting the benefits of Docs as Code (branching, merging, CI/CD) — a pragmatic compromise for enterprise teams that cannot move away from legacy outputs.
When should you consider a hybrid approach?
Consider a hybrid approach if you answer "yes" to any of these questions:
- "We have both developers and technical writers": developers want Git, writers want a visual editor.
- "We need CHM or context-sensitive help, but we also want automated publishing": pure Docs as Code cannot do CHM, but a hybrid HAT with Git can.
- "Our writers are not against Markdown, but they hate the command line and merge conflicts": a Git-backed CMS or GitBook-style solution removes the friction.
- "We want to move toward Docs as Code, but we cannot afford a 6-month migration": hybrid allows for a gradual transition — you can store your docs in Git + visual editor, and later migrate to Markdown + CLI.
- "We have occasional external contributors (translators, open source volunteers)": pure Docs as Code would require them to learn Git, but CMS with simple edit interface removes this barrier.
When should you avoid a hybrid approach?
Hybrid approach is not a universal solution. Avoid it in these cases:
- Your team is small/unified: if your docs are all written by developers who are okay with Docs as Code, pure solution is better; hybrid adds unneeded complexity.
- You need extreme customization: most hybrid tools abstract away the underlying code; if you need complete control over HTML, CSS, JS — hand-rolled static site generator (pure Docs as Code) is the way to go.
- You have a very tight budget: pure MkDocs + GitHub Pages is free; hybrid solutions like GitBook, ClickHelp, or Paligo have monthly subscriptions.
- You produce hundreds of complex PDFs: hybrid tools often compromise on PDF quality; if PDF is your primary output, specialized desktop HAT (MadCap Flare) or DITA-based solution might be better.
The spectrum of documentation tools in 2026
Now, let's think of this in terms of a spectrum — not Docs as Code vs. everything-else, but where various solutions fit:
- Left end (pure visual, no version control): Microsoft Word/Google Docs/early Confluence — avoid for software documentation.
- Center-left (visual editor + file storage, basic versioning): traditional desktop HAT (Dr.Explain, HelpNDoc) + manual file sharing.
- Center (visual editor + Git sync): ClickHelp, Paligo, MadCap Flare (with Git).
- Center-right (Markdown + web CMS + Git): GitBook, Read the Docs (with web editor), Netlify CMS.
- Right end (pure Markdown + CLI + CI/CD): Docusaurus, MkDocs, Sphinx, Antora.
As you move to the right, you get more automation and developer-friendliness, but at the cost of increased technical debt for your writers/editors — there is no one-size-fits-all solution, but the sweet spot is often in the middle (visual editor + Git sync).
Practical advice: start center, move toward right
Based on dozens of documented migrations in the past couple of years (Squarespace, Red Hat, smaller startups), the most successful path is often a gradual transition:
- Phase 1 (Center): adopt a hybrid tool (GitBook, ClickHelp with Git sync); writers remain productive, but developers get the version control.
- Phase 2 (Center-Right): start using Markdown occasionally; train your writers on Markdown syntax; use the hybrid tool's source view more often.
- Phase 3 (Right): if the team is comfortable, migrate to a pure static site generator (MkDocs, Docusaurus); your Markdown is already there, and the CI pipeline is already set up — it's just a theming change.
Jumping straight to the right often fails because writers get overwhelmed; starting in the middle and moving right as they grow their skills has a much higher chance of success.
The bottom line on hybrid approaches
Hybrid approaches are not a compromise — they're a strategic choice for teams that want to balance writer productivity and developer workflows. As the tools have matured in 2026, there's no need to choose between "easy to write" and "easy to automate" — GitBook-style block-based editors, ClickHelp-style WYSIWYG with Git, or Git-backed CMS all demonstrate that hybrid tools can scale.
Before deciding to go all-in on Docs as Code or reject it entirely, ask yourself: "Could a hybrid tool give us 80% of the benefits with 20% of the pain?" For most of your teams, the answer is likely yes.
Decision checklist: is Docs as Code right for your user documentation?
The previous sections covered many factors to consider when choosing between Docs as Code and traditional help authoring tools. This checklist is designed to help you turn those factors into a concrete decision — not a single right answer, but a way to see how your team's context aligns with Docs as Code strengths and where it conflicts.
For each row, check the column that best describes your situation. At the end, look at the patterns — more checks in the left column suggests Docs as Code is a good fit, while more checks in the right column suggest a traditional or hybrid tool may serve you better.
| Consideration | Leans toward Docs as Code | Leans away from Docs as Code |
|---|---|---|
| Who writes the documentation? | mostly developers who already know Git and Markdown | dedicated technical writers with no development background |
| Technical writer comfort with command line | writers are comfortable with Git, CI/CD, and text editors | writers prefer WYSIWYG editors and are not interested in tooling |
| Team size and composition | small team, or team where developers and writers collaborate closely | large team with separate roles and no DevOps support for docs |
| Documentation size | under 200 pages, or well under 500 pages | over 500 pages, or growing quickly toward thousands of pages |
| Output formats needed | HTML website only, or HTML as the primary format | CHM, context-sensitive F1 help, or professional-grade PDF required |
| Screenshots and images | few screenshots, mostly text and code examples | hundreds of annotated screenshots that change with every UI update |
| Content reuse requirements | basic reuse is enough (includes, variables) | complex conditional content or heavy reuse across product versions |
| Non-technical contributors | no product managers, support staff, or marketers need to edit docs | many non-technical stakeholders must contribute regularly |
| Search quality needed | basic client-side search is acceptable for your users | users expect Google-like search with typo tolerance and relevance ranking |
| Analytics requirements | page views are enough, or you have resources to add custom analytics | you need built-in search analytics and documentation dashboards out of the box |
| Budget for documentation tooling | zero budget for licenses, but you have engineering time to maintain tooling | you have budget for licenses but limited engineering time for maintenance |
| Infrastructure maintenance | you have a developer who enjoys maintaining CI/CD pipelines and plugins | you cannot afford ongoing maintenance of the documentation toolchain |
| PDF quality requirement | PDF is nice to have, not a primary requirement | PDF must look professional with precise page breaks and complex formatting |
| Versioning and branching | you need to document multiple software versions in parallel branches | you document only the latest version, or your tool handles versioning differently |
| Open source or external contributors | you accept contributions from external developers via pull requests | all documentation is written internally, no external contributions expected |
How to interpret your results
There's no magic number of checks that makes Docs as Code "correct" or "incorrect." Instead, look at the pattern of your answers. If most of your answers are on the left, Docs as Code is likely a good fit; if most are on the right, a traditional or hybrid tool is probably better.
Strong fit for Docs as Code (most checks in the left column):
- Your team is developer-centric or your writers are willing to learn Git and CI/CD.
- You publish primarily to HTML and don't need CHM or complex PDF.
- Your documentation is moderate in size with few screenshots.
- You have engineering resources to maintain the toolchain.
- You need branching and versioning for multiple product versions.
Mixed fit (roughly equal checks on both sides):
- Consider a hybrid approach (Git-backed WYSIWYG editor, or traditional HAT with Git sync).
- Consider keeping API documentation in Docs as Code but moving user guides to a different tool.
- Consider a phased migration: start hybrid, then move to pure Docs as Code if the team adapts well.
Poor fit for Docs as Code (most checks in the right column):
- Your team has technical writers who are productive in traditional tools and resistant to change.
- You absolutely require CHM, context-sensitive help, or professional-grade PDF.
- Your documentation is image-heavy with many annotated screenshots.
- You have no DevOps support and cannot afford to maintain a custom toolchain.
- A commercial help authoring tool (Dr.Explain, MadCap Flare, ClickHelp) will likely give you a better total cost of ownership.
Final recommendation before you decide
Before committing to any direction, run a small pilot. Don't migrate all of your documentation at once — migrate one user guide or one API reference. For Docs as Code: convert it to Markdown, set up a basic CI/CD pipeline, and ask one writer and one developer to use it for two weeks. Get honest feedback. For a hybrid tool: sign up for a free trial of GitBook, Read the Docs, or ClickHelp. Import the same guide. Ask the same people to try it for two weeks. For a traditional HAT: download Dr.Explain or HelpNDoc. Build the same guide.
After the pilot, you'll know more than you do now. You'll understand how your specific team reacts to each workflow and which tool's pain points are acceptable to you.
Docs as Code is not a silver bullet. It excels for developer-first teams with web-only output — for everyone else, hybrid tools or traditional HAT are often the better option.