If you maintain technical documentation in 2026, there’s a good chance you’re using MkDocs or Material for MkDocs.

You picked it for good reasons. You can get a docs site running in minutes, write everything in Markdown, deploy to GitHub Pages with a lightweight CI pipeline, and end up with a polished-looking documentation site without much setup.

What you might not know is that there is a shift. The team behind Material for MkDocs has introduced Zensical, a new static site generator written from scratch in Rust, and placed Material for MkDocs into maintenance mode. At the same time, MkDocs 2.0 is heading in a direction that won’t remain compatible with Material for MkDocs or much of its existing plugin ecosystem.

If your team builds docs-as-code, then this matters to you. In this walkthrough, you’ll learn what Zensical actually is, how to migrate an existing Material for MkDocs project step by step, and whether it makes sense to move now or wait.

It's 5:15 AM. An alert fires: payments-api, p99 latency > 2000ms for 5m. Olivia's on call. The team has a runbook, but that’s not where she looks for the solution. She completely ignores it. The last few times she followed one at 5 AM, the fix didn’t match the symptom, or the runbook links attached to the alerts were wrong. So she opens Slack, finds a thread from eight months ago, copies the fix, and goes back to bed.

You wrote that runbook. She didn't use it, and she had reasons. This isn't a failure on Olivia's part. Here's why on-call engineers reach for Slack history before the docs you maintain, and what you can do about it.

When a user lands on your documentation, they’re looking for answers. If they hit a wall of text with no starting point or see steps that assume knowledge they don’t have yet. Within minutes, they’ll be frustrated and say it's a bad product.

Believing that if the content is accurate and up to date, the docs are good is wrong. The docs being accurate is a starting point. In this article, we’ll dive into what documentation user experience (UX) is, how writing and structure shape it, what having bad documentation UX costs for your product, and how to improve it.

As a developer, writing changelogs can be a boring task. You already did the work, wrote the code, the commit messages, and shipped the feature. Now you’d need to go through all the commits for a release to create a changelog. This can be a lot.
With this in mind, I created a Python CLI tool that reads your git history and uses AI to generate a clean and publish-ready changelog with one command and one file. Here’s the thinking behind it.

Your documentation has a new reader with no eyes. AI tools like the chatbots, IDE assistants, and Retrieval-Augmented Generation (RAG) systems now stand between your docs and the engineer who needs them. These tools chop your pages into chunks, search for relevant matches, and then generate their responses.

You’re staring at internal documentation at 11 PM, trying to figure out why a deployment pipeline is failing, but it's incomplete. It looks like whoever wrote it stopped midway, like they got pulled into a meeting and never came back. Well, what matters now is that you’re stuck.

As someone who has been in this situation, you should think differently when writing documentation about who you’re writing for and how they would feel with incomplete docs. In this post, you’ll learn how to approach documentation as an engineer.

Some APIs can be easily understood from the moment you open their documentation, while others will leave you hovering from one page to another to get started. The key difference is rarely about the API but the quality of documentation created for it. By studying the documentation practices of companies like Stripe, Twilio, GitHub, Spotify, and X, there are several characteristics that show up consistently. Let’s take a look at some of them.

DevOps teams love talking about automation, observability, infrastructure as code, and deployment speed. But what usually determines whether systems survive incidents, handoffs, or employee exits is accurate documentation.

For teams to ship reliably, they need up-to-date runbooks, READMEs, and architecture docs. In this post, you’ll learn why documentation is non-negotiable in DevOps, the types of documentation in DevOps, best practices and common challenges, and how to overcome them. Let’s dive right in.

Let’s be honest, working on documentation can feel overwhelming. It’s easy to feel stuck when you’re staring at a blank page, or you’re trying to clean up existing content. That’s where Diátaxis comes in.