# docs-as-code Published articles for docs-as-code. This is one page of public article previews, not the complete archive. Follow Next page to continue. Summaries are not the original full articles. ## Doctave is shutting down DevFeed: [Doctave is shutting down]() Original publisher: [Read original article]() Author: Niklas Begley Published: 2026-08-31T06:00:00Z Content type: release Language: en Sources: [Doctave - Build beautiful developer portals with docs-as-code]() Topics: [Documentation](), [migration](), [Open Source](), [MkDocs](), [Markdown](), [OpenAPI Specification]() Tags: [blog](), [configuration](), [docs-as-code](), [documentation](), [markdown](), [migration](), [open-source](), [openapi](), [static-site](), [static-site-generator]() ### AI overview Doctave announces that it will shut down on September 14, 2026. Hosted documentation sites, the dashboard, and builds and deploys will stop operating. Users can continue working from their Git repositories and can migrate to the open-source Docapella static site generator, although server-dependent features such as analytics are unsupported. ### Source excerpt After several years of building documentation tooling, we've made the difficult decision to shut Doctave down. The service will stop operating on September 14th, 2026. We have informed all our customers individually, but are also now posting a public message here. On September 14th, Hosted documentation sites will stop being served The Doctave dashboard will no longer be available Builds and deploys will stop running How this impacts you Your content is yours, and it's already in your repository. Doctave was built on docs-as-code precisely so that your Markdown, OpenAPI specs, and configuration live in Git rather than in our database. Nothing needs to be exported from us to keep writing. You own your docs. Where can I move my docs? We have created an open source static site generator, Docapella, that is mostly compatible with existing Doctave projects. The main change you need to make is renaming doctave.yaml to docapella.yaml. Features that require a server, such as analytics, are not supported, but the content model and general look and feel are the same. Thank you To everyone who wrote documentation with Doctave, sent us feedback, filed bugs, or took a chance on a small team building documentation tooling: thank you. We learned an enormous amount from you, and it genuinely mattered to us. If you have questions about the shutdown or need help planning a migration, get in touch at nik@doctave.com. I'll answer every email I can before we wind things down. - Nik & Anton ## Mintlify introduces a web editor for collaborative documentation publishing DevFeed: [Mintlify introduces a web editor for collaborative documentation publishing]() Original publisher: [Read original article]() Author: Peri Langlois Published: 2026-01-30T00:00:00Z Content type: release Language: en Sources: [Mintlify Blog]() Topics: [Documentation](), [Web](), [configuration](), [Deployment](), [Information Architecture](), [GitHub](), [knowledge-management]() Tags: [announcements](), [docs](), [docs-as-code](), [feature](), [github](), [information-architecture](), [real-time](), [workflow]() ### AI overview Mintlify introduces an improved web editor that combines documentation editing, configuration, structure, publishing, and live preview in one workspace. It extends existing docs-as-code workflows while allowing teams to choose between immediate publishing and pull-request-based review. ### Source excerpt A new web editor that brings publishing, editing, and previewing into one workflow for anyone on your team. ## Making Documentation Simpler and Practical: Our Docs-as-Code Journey DevFeed: [Making Documentation Simpler and Practical: Our Docs-as-Code Journey]() Original publisher: [Read original article]() Author: Rafael Peixinho Published: 2025-10-10T16:00:00Z Content type: article Language: en Sources: [Squarespace](), [Squarespace Engineering Blog]() Topics: [Documentation](), [Development](), [CI/CD](), [Git](), [Pull Request](), [Software Engineering]() Tags: [ci-cd](), [docs-as-code](), [documentation](), [git](), [pull-request](), [workflow]() ### AI overview The Squarespace Domains engineering team describes adopting a docs-as-code approach in which documentation and code are versioned together in Git, reviewed through pull requests, and delivered through a CI/CD pipeline. The article explains how this workflow aims to simplify maintenance, improve consistency and context, and clarify contribution and approval responsibilities. ### Source excerpt In the fast-paced world of software development, documentation often gets a bad rap. It's perceived as a chore, a necessary evil, and sometimes, unfortunately, an afterthought. But what if writing documentation could be as dynamic and collaborative as writing the code itself? What if it could be simpler to write and more practical to use? ## Mintlify vs. Readme: A 2025 Comparison DevFeed: [Mintlify vs. Readme: A 2025 Comparison]() Original publisher: [Read original article]() Author: Tiffany Chen Published: 2025-03-05T00:00:00Z Content type: comparison Language: en Sources: [Mintlify Blog]() Topics: [Documentation](), [Developer experience](), [Tool](), [Artificial Intelligence](), [context](), [Git](), [No-code](), [Model Context Protocol]() Tags: [ai](), [best-practices](), [comparison](), [developer](), [developer-experience](), [docs-as-code](), [documentation](), [git](), [mcp](), [no-code]() ### AI overview A comparison of Mintlify and Readme as developer documentation platforms in 2025. It evaluates AI capabilities, developer experience, collaboration, performance, usability, and editing workflows, finding that Mintlify is positioned as stronger for AI-oriented developer workflows while Readme is presented as stronger for collaboration with non-technical teams. ### Source excerpt If you're choosing a developer documentation tool in 2025, Readme and Mintlify are the two most popular options. ## What makes good API documentation? Best tools and examples DevFeed: [What makes good API documentation? Best tools and examples]() Original publisher: [Read original article]() Author: Emma Adler Published: 2025-01-01T00:00:00Z Content type: comparison Language: en Sources: [Mintlify Blog]() Topics: [Documentation](), [API](), [Artificial Intelligence](), [AI-assisted coding]() Tags: [ai-trends](), [api](), [api-documentation](), [article](), [docs-as-code](), [generative-ai](), [guide]() ### AI overview A comparison of API documentation tools, including Mintlify, ReadMe, GitBook, SwaggerHub, Stoplight, Postman, Docusaurus, and Redocly. It evaluates docs-as-code workflows, AI readiness, interactive API explorers, collaboration, and pricing, with recommendations for different team needs. ### Source excerpt The API documentation software landscape is evolving fast in 2025. With AI advancements and rising developer expectations, companies must elevate their developer documentation to stay competitive. ## Adopting Docs as Code in Developer Workflows DevFeed: [Adopting Docs as Code in Developer Workflows]() Original publisher: [Read original article]() Author: Tiffany Chen Published: 2024-11-19T00:00:00Z Content type: tutorial Language: en Sources: [Mintlify Blog]() Topics: [Documentation](), [Git](), [Markdown](), [version-control](), [Pull Request]() Tags: [ai-trends](), [also](), [docs-as-code](), [documentation](), [git](), [markdown](), [version-control]() ### AI overview This article explains how a Docs as Code approach brings documentation into existing developer workflows through plain-text formats such as Markdown, Git-based version control, change reviews, and automated builds. It also recommends cultural practices such as recognizing documentation work in performance reviews and requiring documentation updates alongside code changes. ### Source excerpt We all suffer from documentation lagging behind product updates. ## Doctave Studio 2.0 Beta: The editor for technical writing and docs-as-code DevFeed: [Doctave Studio 2.0 Beta: The editor for technical writing and docs-as-code]() Original publisher: [Read original article]() Author: Doctave Team Published: 2024-10-08T05:00:00Z Content type: release Language: en Sources: [Doctave - Build beautiful developer portals with docs-as-code]() Topics: [Documentation](), [Tooling](), [Markdown](), [OpenAPI Specification](), [CI/CD]() Tags: [announce](), [assets](), [auto-complete](), [beta](), [blog](), [ci-cd](), [components](), [docs](), [docs-as-code](), [editor](), [real-time](), [technical-writing]() ### AI overview Doctave announces the public beta of Doctave Studio 2.0, an editor for technical writing and docs-as-code. The beta includes a modern editor, real-time Markdown and OpenAPI previews, auto-complete for links and assets, and inline Markdown error reporting. ### Source excerpt We're excited to announce that Doctave Studio 2.0 is now available in public beta! Doctave Studio is a new editor for technical writing and docs-as-code, and we're excited to share it with you. Want to see it in action? Here's a quick introductory video of Doctave Studio 2.0: If you just want to see how to participate in the beta, you can jump straight to the end of this post Why build a new editor? One of the biggest issues with docs-as-code is inconsistent tooling. While there are great tools out there (like Vale), it's really hard to create a great authoring environment for docs-as-code. Getting spell check, broken links checking, auto-complete, and more configured is often too complex or time consuming, that lots of authors live without these tools. This problem is compounded when you have multiple authors collaborating on the same documentation. One will have a spell checker configured, one will have auto-complete configured, another doesn't have a broken links checker. The lack of a common authoring system causes friction, confusion, and ultimately raises the barrier for contributions. And after all that, you still need to set up these same checks in your CI/CD pipeline! This is what we set out to solve with Doctave Studio 2.0. We've already made it easy to host, version, and review docs-as-code projects with our existing product. Now we're taking the next logical step and improving the docs-as-code authoring experience. What's in the Doctave Studio 2.0 beta? Today we're launching Doctave Studio 2.0 into beta with a few key features: A new, modern editor with a focus on the authoring experience Real-time previews of your content as you type (Markdown and OpenAPI!) Powerful auto-complete for your links, assets, and components Great error-reporting inline in your Markdown Let's see some of these in action! Real-time previews The right-side panel in Doctave Studio is dedicated to a real-time preview window. It shows you what your content will look like once publi ## How to write documentation that developers want to read DevFeed: [How to write documentation that developers want to read]() Original publisher: [Read original article]() Author: Han Wang Published: 2024-10-08T00:00:00Z Content type: article Language: en Sources: [Mintlify Blog]() Topics: [Documentation](), [Developer experience]() Tags: [best-practices](), [developer-experience](), [developers](), [docs-as-code](), [documentation](), [how-to](), [technical](), [writing]() ### AI overview This article explains how to create developer documentation by understanding the audience, designing clear navigation, treating documentation as code, balancing automation with human expertise, collaborating to maintain quality, and measuring impact through quantitative and qualitative feedback. ### Source excerpt Top-tier documentation stands out immediately--it's thoughtful, comprehensive, and easy to navigate. ## Markdown vs. DITA: Balancing Simplicity and Structure in Technical Documentation DevFeed: [Markdown vs. DITA: Balancing Simplicity and Structure in Technical Documentation]() Original publisher: [Read original article]() Author: Niklas Begley Published: 2024-06-06T07:00:00Z Content type: comparison Language: en Sources: [Doctave - Build beautiful developer portals with docs-as-code]() Topics: [Markdown](), [Documentation](), [XML](), [HTML](), [OpenAPI Specification]() Tags: [blog](), [docs-as-code](), [documentation](), [html](), [markdown](), [openapi](), [technical](), [technical-documentation]() ### AI overview This comparison examines Markdown and DITA as authoring choices for technical documentation. It presents Markdown as easy to learn and widely supported, while describing DITA as a more structured XML standard that supports content reuse, document consistency, and publishing in multiple formats, with a higher learning curve. ### Source excerpt When embarking on a new documentation project, one of the first, and quite consequential choices you have to make is what tools and formats to pick. Do you go with Markdown, the ubiquitous and light-weight markup language with a low barrier to entry, or do you instead reach for an authoring system like DITA that lets you enforce structure and reuse content from day one? In this post we're going to look at both options and evaluate the pros and cons of both approaches, and when one might choose one over the other. What is Markdown? Markdown was originally developed by John Gruber back in 2004. It was designed as an easy way to convert text into HTML easily. Here is John describing Markdown in the introduction: Markdown is a text-to-HTML conversion tool for web writers. Markdown allows you to write using an easy-to-read, easy-to-write plain text format, then convert it to structurally valid XHTML (or HTML). 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 # Rocket Launch Sequence 1. **Pre-launch Jitters** - Double-check that the pointy end is facing up - Ensure the rocket isn't just a giant firework - Cross fingers and hope for the best 2. **Blastoff!** - Light the candle and watch the show - Try not to think about the astronomical fuel costs - Wave goodbye to the rocket (and your paycheck) 3. **Celebrate or Commiserate** - If the payload reaches orbit, break out the champagne - If not, break out the tissues and start drafting the apology email - Either way, start planning for the next launch (and budget) Example Markdown snippet Since then, Markdown has exploded in popularity. It has become the lingua franca for all kinds of technical content and blogs. Developers have embraced the simplicity of Markdown. Most new programming languages support Markdown as part of their docstrings, OpenAPI supports Markdown in description fields, and most static site generators have built-in Markdown support. The ecosystem of Makdown tooling is vast. This is why the docs-as-code movement has mo ## How we are driving up the quality of internal technical documentation at Volvo Cars DevFeed: [How we are driving up the quality of internal technical documentation at Volvo Cars]() Original publisher: [Read original article]() Author: Gary Niemen Published: 2024-02-26T11:39:27Z Content type: article Language: en Sources: [Volvo Cars Engineering - Medium]() Topics: [Documentation](), [Developer experience](), [engineering-culture]() Tags: [backstage](), [blog-post](), [developer-experience](), [docs-as-code](), [documentation](), [engineering](), [platform-engineering](), [technical-documentation](), [technical-writing](), [writing]() ### AI overview The article describes how a small technical-writing team at Volvo Cars is improving the quality of internal technical documentation for more than 4,500 software engineers. It presents treating documentation like code as one part of a broader approach to scaling technical writing. ### Source excerpt How we are driving up the quality of internal technical documentation at Volvo Cars -- with just a few technical writersTreating docs like code is part of it -- but not all of itGenerated by Deep Dream Generator by Author There are many components to a great developer experience. One of them, I think we can all agree, is to have quality internal technical documentation. But how to get to that place? Few engineering organisations prioritise recruiting technical writers above software engineers. And software engineers, typically, and perfectly understandably, prefer to be coding rather than writing. The answer in the tech industry of today -- is to find a way to scale tech writing. Consider this... Many years ago, when I was working as a technical writer at one of the world's leading IT companies, the sacred ratio was one tech writer for 8-10 developers. Later, when I moved on and started working as a documentation lead in FinTech, I tried to get the company to implement this ratio -- but, alas, it was never going to fly. We settled on about 1 to 30. I was not too pleased. If only I had known what was to come. When I started working in big tech, it was more like 1 to 1000. And now at Volvo Cars, it is -- well that's what this blog post is all about. How just a few technical writers (two within a centralised developer experience function and one focusing on a specific part of the organisation) are driving up the quality of internal technical documentation among 4500+ software engineers at Volvo Cars. (What's the ratio now, huh?) As we'll describe in this blog post, moving to treating docs like code is one key component of scaling technical writing, but not the only one. Implement docs like code About five years ago when at a previous company, I stumbled across Google technical writing manager, Riona MacNamara's talk from the 2015 Write the Docs conference, Documentation, Disrupted: How Two Technical Writers Changed Google Engineering Culture. Riona was talking about solving p ## Continuous documentation: publishing docs early and often DevFeed: [Continuous documentation: publishing docs early and often]() Original publisher: [Read original article]() Author: Niklas Begley Published: 2024-01-23T07:00:00Z Content type: tutorial Language: en Sources: [Doctave - Build beautiful developer portals with docs-as-code]() Topics: [Documentation](), [CI/CD](), [monorepo](), [Git](), [GitHub]() Tags: [blog](), [ci-cd](), [docs-as-code](), [documentation](), [git](), [github](), [monorepo]() ### AI overview This article explains continuous documentation as a docs-as-code practice: update documentation incrementally alongside product changes, make documentation part of the release definition of done, and review and deploy documentation with code. It also discusses enabling contributions from engineers, technical writers, and product managers. ### Source excerpt One of the key pillars of docs-as-code is releasing changes via CI/CD. Just as how software is often released continuously, we can keep our documentation up to date as the product changes. This lets us achieve continuous documentation: instead of large bulk releases, we can incrementally improve our documentation, as we make changes to our product. Let's dive into how continuous documentation is implemented in practice. Making it easy to make changes The key to continuous documentation is making it easy to contribute to documentation. We want to lower the barrier to making changes, and empower contributors to make the docs better. Let's see how! Smaller, iterative changes The bigger the change, the harder it is to make. Everyone who has worked in the technology industry has seen large project spiral out of control, missing deadlines, and seemingly never ending. Fast-moving teams get around this problem by splitting work into smaller chunks. Instead of a large monolithic release, preferring smaller, iterative changes that are easier to manage. Small changes are easier to review, have less risk, and can be shipped with fewer checks in place. Releasing docs with code It makes sense to update your product and documentation at the same time. Documentation should be in your "definition of done": a hard requirement for a feature to be released. A Git monorepo, it's natural to even have code and documentation changes in the same branch or pull-request. Engineers and technical writers can work in the same branch, and eventually merge and deploy the code and documentation in tandem. This is what we do at Doctave. We use a monorepo with a dedicated /docs folder. Every customer-facing feature will have documentation changes included, and get reviewed as part of the same pull-request on GitHub. A multi-repository setup requires some more coordination. but the same principles apply. Every feature change should have a corresponding change in the documentation repository. Empowerin ## Documentation versioning best practices with docs-as-code DevFeed: [Documentation versioning best practices with docs-as-code]() Original publisher: [Read original article]() Author: Niklas Begley Published: 2023-10-20T07:00:00Z Content type: tutorial Language: en Sources: [Doctave - Build beautiful developer portals with docs-as-code]() Topics: [Documentation](), [Git](), [releases](), [Development]() Tags: [best-practices](), [blog](), [development](), [docs-as-code](), [documentation](), [git](), [releases](), [version]() ### AI overview This tutorial explains how to version documentation alongside software releases in a Git-based docs-as-code workflow. It covers semantic or date-based versioning, release branches, hotfixes, patch releases, and cases where product versioning is unnecessary but API versioning may still be needed. ### Source excerpt Many software products end up having multiple releases over their lifetimes. When this happens, the documentation needs to be versioned along with the product. In this post we will look at documentation best practices when using a Git-based docs-as-code workflow. Software versioning basics Before going into how we should version documentation, let's take a look at how software projects generally handle versioning. Disclaimer: there is more than one way to version software. The method outlined in this post works for many projects, but there are other valid workflows too. Versioned releases Products like Windows, PostgreSQL, or React JS all have versioned releases. Every once in a while, depending on their release cadence, a new version with new features is released. A long list of versions for PingCap's TiDB documentation Different projects will use different versioning schemes, but Semantic Versioning is a popular way of giving structure to your version numbers. Another option is using a date-based scheme. Usually, different versions are managed in separate Git branches. A typical branching strategy is to have all work for the upcoming release happening on a main or development branch. Then, when a new release is ready, a new branch is created from the main branch and named after the release (for example v4.0). 1 2 3 4 5 6 7 main # Development happens in this branch * | v4.0 # New branch for the release * * | / * ---- | There's a few reasons for this. Firstly, it's clear what code belongs in the release, and what does not. But importantly, you can apply hotfixes to the release branch: 1 2 3 4 5 6 7 8 9 main * | v4.0 * * # <- New hotfix commit | | * * | / * ---- | This allows you to update and fix the 4.0 version, while you keep moving forward in your main branch towards the next release. Perhaps you'll even release a patch release with bug fixes: a 4.0.1. This strategy also makes it clear which features and commits belong to which version. You don't have code for multip