5 posts tagged with "technical-writing"

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.