![\"Timeline](\"https://faithwachukwu.com/img/blog/zensical-timeline.png\")
The ecosystem shift from Material for MkDocs to Zensical, marked by stagnation, announcement, and rapid post-launch development through 2026.
![\"#\"](\"https://faithwachukwu.com/img/blog/mkdocs1.png\")
\nIf you maintain technical documentation in 2026, there’s a good chance you’re using MkDocs or Material for MkDocs.
\nYou 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.
\nWhat 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.
\nIf 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.
\nMkDocs has been around since 2014. It’s a simple Python-based static site generator that works by pointing it to a folder of Markdown files, providing a YAML config, and generating a searchable documentation site. It has a minimal and clean architecture.
\nIn 2016, Martin Donath (known online as Squidfunk) released Material for MkDocs. Technically, it’s a theme, but it has evolved into a framework for technical writing. We’re talking about tabs, admonitions, code annotations, versioned navigation, and instant search.
\nHere's the part most people miss: Material for MkDocs and MkDocs are two different projects with two different teams. Squidfunk's team maintains Material for MkDocs. They have no control over MkDocs itself; they just depend on it.
\nAs for the underlying MkDocs engine, MkDocs 1.x has been effectively unmaintained since August 2024, with version 1.6.1, released on August 30, 2024. It remains the last release to date, as of the time of writing this article.
\nWith issues piling up and no maintained path forward, the Material for MkDocs team faced a strategic question: keep building on a stagnant dependency, or move, and they chose to move.
\nOn November 5, 2025, the Material for MkDocs team announced Zensical — a static site generator they'd been building from scratch for over a year. About six days later, they shipped Material for MkDocs 9.7.0, which made all previously paid “insiders” features free, and put the project into a 12-month maintenance window covering critical bug fixes and security updates only.
\nIn late January 2026, MkDocs 2.0 entered pre-release as a ground-up rewrite with breaking changes that would have broken Material for MkDocs and the plugins built on top of it based on the team's analysis. The decision to build Zensical was already validated.
\nThe ecosystem shift from Material for MkDocs to Zensical, marked by stagnation, announcement, and rapid post-launch development through 2026.
Zensical is a modern static site generator designed to replace the MkDocs stack while staying backwards-compatible with existing projects. It’s built from years of experience, so they’ve learned what works and what doesn’t. They created it to fix the problems in MkDocs and go beyond what MkDocs can do.
\nAlthough it’s a new project, it’s compatible with your existing mkdocs.yml. Not all plugins are supported yet, but your core configuration works.
Zensical is built in Rust, with a thin Python layer on top using PyO3. That’s why you install it with pip like any Python package, but it runs much faster, closer to a Rust tool than a typical Python one.
Underneath, two components do the heavy lifting:
\nZensical ships two theme variants. The classic variant, which matches the Material for MkDocs look and the modern variant, which gives your site a fresh appearance.
\nThere is, however, an honest caveat; Zensical is still in its early stage (alpha). The current version on PyPI is 0.0.43, released May 19, 2026, as of the time of writing. However, the project has shipped frequently since going public in November 2025.
\nEven though it’s in its early stages, it works. The GitHub Repo already has 4,700+ stars, and major projects are already migrating.
\n![\"Zensical](\"https://faithwachukwu.com/img/blog/zensical.png\")
Zensical’s landing page introducing its modern documentation platform.
Before migrating to Zensical, make sure your current setup meets the following prerequisites.
\nBefore making changes, audit your project dependencies against the Zensical compatibility documentation. To get a clear picture of what you are working on, spend time looking at these three areas:
\nplugins: in your mkdocs.yml. Zensical supports many of them, but not all yet. So make sure you check the compatibility matrix below or Zensical's official plugins page before committing to a migration timeline.material.extensions.*. You’ll need to rename those later.If a key plugin isn’t supported yet, don’t force it. Either you wait or plan to build the missing piece yourself.
Once you’ve reviewed these, follow these steps:
\ngit checkout -b migrate/zensical
You’ll keep main as your baseline. When something breaks during migration, you need something to compare against, or in case a rollback is needed. Otherwise, you will spend more time guessing.
Install Zensical in a new virtual environment. You won’t want to mess up your existing mkdocs environment. Run the commands:
\npython3 -m venv .venv-zensical
source .venv-zensical/bin/activate # Windows: .venv-zensical\\Scripts\\activate
pip install --upgrade pip
pip install \"zensical==0.0.43\" # Pin the version. Alpha velocity is real.
zensical --version
For uv users:
uv tool install \"zensical==0.0.43\"
You don’t need to switch to zensical.toml yet, Zensical works with mkdocs.yml. From the directory containing your mkdocs.yml file, run the command:
zensical build --clean
Zensical reads mkdocs.yml directly and writes to site/ . This will show you any first-build errors, and you can fix them.
Some of the common ones include:
\n| Error | Fix |
|---|---|
docs_dir cannot be set to '.' | Set docs_dir to a subdirectory such as docs and move your source files there. |
Unknown plugin <name> | Plugin not yet supported. Check the compatibility matrix; remove the plugin or stay on MkDocs. |
| Unknown setting remote_branch / hooks / etc. | One of the unsupported settings. Remove. |
material.extensions.* unresolved | Rename to zensical.extensions.* — see step 5. |
To minimize drift during your migration, start with the classic variant.
# mkdocs.yml
theme:
name: material
variant: classic # add this
You can switch to modern later if you want.
Do a namespace swap from material. to zensical.:
# Before
markdown_extensions:
- pymdownx.emoji:
emoji_index: !!python/name:material.extensions.emoji.twemoji
emoji_generator: !!python/name:material.extensions.emoji.to_svg
# After
markdown_extensions:
- pymdownx.emoji:
emoji_index: !!python/name:zensical.extensions.emoji.twemoji
emoji_generator: !!python/name:zensical.extensions.emoji.to_svg
For icons, swap the Material brightness icons for Lucide equivalents: material/brightness-7 → lucide/sun, and material/brightness-4 → lucide/moon.
Run the command:
\nzensical serve
# default: http://localhost:8000
Open http://local:8000 and click through your docs. Don't just spot-check the homepage.
Compare against your live MkDocs site and look for:
\nIf you use mike for versioning, double-check version switching. There's an official mike fork maintained by the Zensical team, you'll install it from the Git URL listed in compatibility documentation.
Some setups need temporary pinning to avoid conflicts.
If you have a pipeline already setup, replace your CI build command with:
\nzensical build --clean
A typical GitHub Actions workflow looks like this:
\nname: Documentation
on:
push:
branches:
- main
permissions:
contents: read
pages: write
id-token: write
jobs:
deploy:
environment:
name: github-pages
url: ${{ steps.deployment.outputs.page_url }}
runs-on: ubuntu-latest
steps:
- uses: actions/configure-pages@v5
- uses: actions/checkout@v5
- uses: actions/setup-python@v5
with:
python-version: 3.10
- run: pip install \"zensical==0.0.43\" # Add installation commands for other dependencies if needed.
- run: zensical build --clean
- uses: actions/upload-pages-artifact@v4
with:
path: site
- uses: actions/deploy-pages@v4
id: deployment
If you're on Read the Docs, build with Zensical and copy the output into their expected directory. The canonical config is in Zensical's setup docs.
\nIf anything breaks in production after deployment, the rollback is straightforward: revert the merge of the migrate/zensical branch.
That’s it. Your mkdocs.yml keeps working, and your Markdown files don’t need changes to work with Zensical. Your templates, override, CSS, and JavaScript extensions carry over the same configuration because Zensical uses the same HTML structure and Python-Markdown parser under the hood.
Plugin compatibility is one of the first things teams ask about during a migration, but right now the information is spread across Zensical’s docs, GitHub backlog, and community threads. To make things easier, here’s a consolidated table based on the official Zensical plugin compatibility page as of May 2026.
\nThe Zensical team analyzed the top 1,000 GitHub repositories using Material for MkDocs to determine which plugins to support first. They grouped the work into two tiers. Tier 1 covers the highest-priority plugins and focuses on getting close to feature parity first, while Tier 2 plugins are still in the backlog.
\nA few details matter if you’re planning a migration:
\nawesome-nav, not awesome-pages. If your project still depends on awesome-pages, you’ll likely need a two-step migration: move from awesome-pages to awesome-nav in MkDocs first, then migrate to Zensical.typeset plugin is a good example. Material for MkDocs has already deprecated it because the upcoming modular navigation system will support rich navigation content natively.If your site depends on a Tier 2 plugin that Zensical hasn’t shipped yet, you have options to choose from: wait for support, replace the feature with a workaround, or stay on Material for MkDocs during its 12-month maintenance window until the matching Zensical module becomes available.
\nBased on where the project stands today.
\nMigrate now if you:
\nWait a quarter or two if you:
\nThe best advice is for you not to wait indefinitely, though. And that’s because Material for MkDocs is in a 12-month maintenance window that already began November 6, 2025, with focus on critical bugs and security fixes only, so no new features will be released. After that, you’ll be running unmaintained software.
\nThere are early adopters already talking about how easy the process is. Here are some:
\nThe plugin ecosystem hasn't fully caught up though, so if your project depends on a lot of plugins, expect some friction.
\nIn my view, for docs-as-code, Zensical is bigger than the tool itself. There are three things worth noting about it:
\nEnd of the sponsorware era: Material for MkDocs used a model in which sponsors received early access to features. But with the 9.7.0 release, all Insider features became free for everyone. Zensical, however, replaced sponsorware with Zensical Spark — a support-and-services tier aimed at organizations rather than individual developers.
\nCompatibility: The team could have shipped a clean-break rewrite and forced the users to rewrite their docs, but they didn’t. They shipped something that can work with your existing config. That’s a good product decision, and it’s why adoption is moving faster.
\nDocs-as-code is maturing: For a long time, documentation tools lagged behind developer tools. Now, tools like Zensical with faster builds and better search are catching up. This raises the standard higher, and that’s good for anyone writing docs.
\nMkDocs 1.x is no longer actively maintained, and Material for MkDocs has received only limited support for about a year. The same team has already moved forward with Zensical, which is faster, still works with your current setup, and is actively being built.
\nIf your docs matter to your product, your team, or your users, then you need a plan. Start with the compatibility matrix, try a small migration in a separate branch, see what breaks, and plan from there. If you're stuck on a Tier 2 plugin, watch the Zensical backlog or consider contributing a module.
\nFor deeper context on the ecosystem dynamics that led here, Florian Maas's The Slow Collapse of MkDocs is the most thorough public account, and Martin Donath's interview on Talk Python #542 covers the technical and strategic reasoning behind Zensical from the team itself.
", "url": "https://faithwachukwu.com/blog/migrating-from-material-for-mkdocs-to-zensical/", "title": "Migrating from Material for MkDocs to Zensical: A Documentation Engineer Walkthrough", "summary": "If you maintain technical documentation in 2026, there’s a good chance you’re using MkDocs or Material for MkDocs.", "date_modified": "2026-05-20T00:00:00.000Z", "author": { "name": "Faith Wachukwu", "url": "https://faithkovi.xyz" }, "tags": [ "technical-writing", "documentation", "Zensical", "Material for MkDocs", "Docs" ] }, { "id": "https://faithwachukwu.com/blog/why-on-call-engineers-ignore-your-runbooks/", "content_html": "![\"#\"](\"https://faithwachukwu.com/img/blog/oncall-cover.png\")
\nIt'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.
\nYou 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.
\nIn most cases, documentation is written for a reader who has time. They have the mental bandwidth to read prose, follow a tutorial sequentially, and absorb all the concepts. For an on-call engineer like Olivia, she doesn’t have that time. She’s triaging. She scans, copies and pastes, and bails if it doesn’t work. If your runbook starts with three paragraphs of context before the first command, she’s gone.
\nThe Google SRE book made this point years ago: the quantity of on-call can be calculated by the percentage of time spent by engineers on on-call duty.
\nSo, for on-call engineers, a runbook isn’t documentation in the literary sense. It’s a tool. What matters is whether it helps shorten the incident.
\nThere are a few patterns that show up in almost every team that struggles with on-call docs. Let's take a look at some of them:
\nThe docs aren’t where the alert is. The runbooks live on Confluence, the alert fires on PagerDuty, the dashboard is in Grafana, while Olivia is in her terminal. None was linked to the others. She is context-switching more often to get information; this is costing her thirty seconds per switch and a little more of her composure while she is frantically searching for a solution.
\nThe runbook is a tutorial, not a checklist. It explains in deep details how the payments service works. It does not say if p99 > 2s, check queue depth first; if queue depth > 10k, scale workers; if workers are healthy, page the database team. The Diataxis framework nailed this distinction between tutorials, how-to-guides, references, and explanation. They are four different things, and runbooks are how-tos. You don’t need to start explaining in details.
\nThe runbook is stale. It tells Olivia to restart payments-worker meanwhile, that service was renamed txn-processor seven months ago. She runs the command, gets service not found, and now she trusts nothing on that page.
\nNobody owns it. The original author has left the company. The team that runs the service has never opened the doc to update it. There have been countless postmortem-generated action items to update runbooks that weren’t assigned to anyone or verified either.
\n![\"A](\"https://faithwachukwu.com/img/blog/oncall-1.png\")
A flowchart showing a bad runbook chain reaction: the alert fires, the documentation link fails, the commands are outdated, and the engineer loses time during an incident.
For teams whose runbooks actually get read, share a few things in common.
\nThey link the runbook from the alert itself. PagerDuty, Opsgenie, and Grafana Alerting all support adding runbook URLs in the alert payload. If your alert doesn’t include the link, it's like the runbook isn't available.
\nThey start with action to take, not lots of context. The first thing on the page is what to do, how severe, what the symptoms look like, and commands you can copy to solve it. The explanations come much later, for those who want them after they’ve solved the problem.
\nThey write for the worst version of the reader. The runbook works for someone who is half-asleep, new to the team, and has their adrenaline up. Not only for the senior engineer who wrote it.
\nThey treat every incident as a doc bug. As Atlassian’s incident handbook puts it: \"Every incident should be tracked and documented so you can identify trends and make comparisons over time.\"
\nThey keep runbooks close to code. The Markdown is in the same repo as the code. The runbooks are reviewed in the same PR change that needs it. When docs live far from the code, they tend to rot. And that’s because those writing the code for the fix aren’t going to navigate to a separate wiki to update it.
\n![\"An](\"https://faithwachukwu.com/img/blog/oncall3.png\")
Runbook link included directly in the alert payload for quick access during incidents.
If you’re a docs engineer and the on-call team keeps ignoring your work, it’s tempting to blame them for not searching, reading, or following the process. With a customer-facing outage happening, they definitely would want a solution fast.
\nThe reader, just like Olivia you’re writing for, is exhausted, scared, and looking for one specific sentence that tells her what to do next to fix the problem.\nMake sure you write that sentence, put it at the top, link it from the alert, update it after every incident, and delete what is not needed.
\nThe on-call engineer doesn’t read your docs, so make docs that don’t need to be read, but only used.
", "url": "https://faithwachukwu.com/blog/why-on-call-engineers-ignore-your-runbooks/", "title": "Why On-Call Engineers Ignore Your Runbooks ", "summary": "It's 5 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.", "date_modified": "2026-05-18T00:00:00.000Z", "author": { "name": "Faith Wachukwu", "url": "https://faithkovi.xyz" }, "tags": [ "On-call", "documentation", "technical writing", "engineer" ] }, { "id": "https://faithwachukwu.com/blog/documentation-ux-and-why-matters-more-than-accurate-content-alone/", "content_html": "![\"#\"](\"https://faithwachukwu.com/img/blog/cover-doc-ux.png\")
\nWhen 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.
\nBelieving 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.
\nDocumentation User Experience(UX) is the overall experience users have while interacting with your documentation. It goes beyond the layout, color schemes, or which static site generator you used. It includes how content is structured, how language is used, how the navigation works, and most importantly how well the documentation meet the users where they are.
\nGood documentation UX helps users answer three questions quickly:
\nThe moment the answer to any of these questions becomes “I’m not sure”, the experience has already started to crack. And once that crack forms, users rarely stick around for you to fix it.
\n![\"Three-step](\"https://faithwachukwu.com/img/blog/find-understand-act.png\")
Documentation UX problems can arise from writing too close to the product. When you build a feature, you understand it deeply, but the users don’t, and that deep understanding can be a blind spot. You’ll write docs that make perfect sense to someone who already knows how everything fits together. But for a new user discovering it for the first time, that's a different story.
\nThese patterns show over and over again:
\nThe content itself might be technically correct, but if users can’t easily act on it, the documentation still fails them.
\nGood documentation UX shows up in the little things users never have to think about like clear headings that guide their eyes, sections that unfold in a predictable order, and language that doesn't make them pause and re-read.
\nThe choice of words, tone, and sentence structure all shape how quickly users absorb information. Using short sentences helps users scan, familiar words lower the barrier to understanding, and the active voice makes the instructions easier to follow. Following these doesn’t mean you should dumb things down. It means you should be intentional as a writer.
\nWhen it comes to structure, users don’t read documentation top to bottom. They jump in from a search result, scan for what they need, and move on. The pages in your documentation needs to support that kind of behaviour. Clear headings, predictable section order, and logical grouping let users locate content fast. Strong documentation UX comes from deliberate choices: deciding what users need first, what can wait, and what doesn't belong on the page at all.
\nWhen documentation UX is poor, the damage spreads quickly. Users will take longer to onboard, and you’ll have support tickets piling up with questions the docs should have answered. You’re losing trust in the documentation and pushing the users to other sources like Stack Overflow, community forums, or even worse, a competitor with better docs.
\nOver time, users will not say “The documentation UX is bad”. They’ll frame it as:
\nEach of these statements makes it sound like the product has a problem. And in a way, it does because documentation is a product. This shapes how people feel about what you've built, whether they consciously realize it or not.
\nYou don't need a redesign, a new tool, or a bigger team to start making documentation UX better. Small, focused changes go a long way.
\nWhen you apply small changes like these over time, there’ll be a noticeable difference in how users experience your documentation and your product.
\nDocumentation is part of your product experience. Treating it that way through thoughtful UX, clear writing, and intentional structure changes how people interact with everything you build. And once you start seeing your docs through a UX lens, you won't want to go back.
", "url": "https://faithwachukwu.com/blog/documentation-ux-and-why-matters-more-than-accurate-content-alone/", "title": "Documentation UX: Why It Matters More Than Accurate Content Alone", "summary": "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.", "date_modified": "2026-04-13T00:00:00.000Z", "author": { "name": "Faith Wachukwu", "url": "https://faithkovi.xyz" }, "tags": [ "Documentation UX", "documentation", "technical writing" ] }, { "id": "https://faithwachukwu.com/blog/i-built-a-cli-tool-that-writes-changelogs-for-you/", "content_html": "![\"I](\"https://faithwachukwu.com/img/blog/cli-tool.png\")
\nAs 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.
\nWith 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.
Developers write commit messages when creating a pull request to close out tasks they are assigned. They’d create commit messages like: fix: resolve edge case in auth token refresh or chore: bump deps. This is useful for context in git blame, but useless to a user reading release notes.
A good changelog translates those commit messages into something a user actually cares about. Like Fixed a bug where login sessions expired unexpectedly can be easily understood by the user than Fix: token refresh edge case.
The step where these messages are translated is where teams give up. It takes correct judgement, context, and effort for a changelog not to feel like an afterthought.
\nI wanted this CLI tool to fit into existing workflows and not replace them entirely. Developers live in the terminal, so it should be easy to use the tool there. As a developer, you’ll simply run the command in your terminal, which reads your git history, sends the commits to an LLM, and saves a formatted changelog.
\npython changelog.py --repo ./my-project --version 1.1.0 --output CHANGELOG.md
I tested it out on a GitHub Repository I found online called Vibevoice:
\n![\"The](\"https://faithwachukwu.com/img/blog/changelog2.png\")
This created a CHANGELOG.md file in the project directory that looked like this:
## [v1.0.0] - 2026-03-30
**Added**
- Gradio ASR demo with video support, including demo audio/video files and Cloudflare tunnel integration. (09ca114f)
- Data parallel (DP) support to the vLLM server launcher, allowing for multiple GPU replicas with automatic load balancing. (9634518c)
- Tensor parallel (TP) support to the vLLM server launcher. (9634518c)
- Announcement regarding VibeVoice ASR integration into Transformers v5.3.0, with a link to the Hugging Face release page. (7e73beec)
**Changed**
- Nginx worker processes are now set to 2x DP replicas for optimal HTTP throughput, rather than defaulting to 'auto'. (cd945395)
- Implemented nginx-based data parallelism for improved ASR throughput, utilizing a reverse proxy to avoid single-process HTTP bottlenecks. (3817f74d)
- Per-worker environment variables in DP mode are now auto-tuned, ensuring correct settings are passed to each worker subprocess. (e6b65abb)
**Fixed**
- Resolved GPU Out-of-Memory (OOM) errors by restoring sequential encoder usage, as the batch encoder caused memory issues under heavy load. (5cd81bb4)
**Documentation**
- Added Vibing download links. (c766f12e)
- Added Vibing demo video to the news section. (8f133837)
- Corrected bold formatting in the news section. (0857b6d5)
- Added news about Vibing voice input adoption. (c8371b6b)
- Added the Trendshift #1 trending badge to the README. (b691f991)
- Updated documentation for multi-GPU deployment configurations, including DP, TP, and hybrid setups. (9634518c)
With this, you have your changelog file ready.\nThis also works with a CI/CD pipeline. I included a GitHub Actions workflow in the project README so you can auto-generate changelogs on every release.
\nWhen it came to choosing an AI provider, I started with Anthropic’s Claude API because I was already familiar with it. Claude produces excellent results, follows instructions well and respects the formatting constraints.
\nThen I hit a problem with it: the Anthropic API requires a paid key. For a tool that runs maybe once or twice per release cycle, that looked excessive.
\nSo I added Google Gemini as the default provider. Its free tier gives a good amount of requests per day.\nWith that, the tool supports both Gemini by default and Claude with a –provider claude flag.
The interesting part of this project is the prompt. The LLM need to do several things consistently: group commits by type (Added, Changed, Fixed, Security, etc.), rewrite these commit messages into user-friendly descriptions, drop noise like merge commits and typo fixes, keep commit hashes to make it easy to trace, and follow the Keep a Changelog format without deviating from it.
\nGetting all of this right took iteration.\nThe prompt lives in a build_prompt() function in the script, so you can customize it. The prompt is the part you can tweak to suit your needs.
Building this reinforced something I keep telling people: prompt engineering is part of documentation engineering. The prompt I wrote for this tool is basically a style guide for the changelog. It tells the LLM what voice to use, how to structure content, what to include, and what to leave out. That's exactly what a documentation style guide does for human writers.
\nIf you're a technical writer wondering how AI fits into your career, this is the answer. You're not being replaced. You're being promoted from writing every word to designing the systems that generate them.
\nThe project is open source. Clone it, point it at any git repo, and see what it produces.
\nGitHub: https://github.com/FaithKovi/changelog-generator
\nIt takes a few minutes to set up; the README walks you through every step. If you build something with it or find a bug, open an issue. I'd love to hear how other teams are handling their changelog workflows.
", "url": "https://faithwachukwu.com/blog/i-built-a-cli-tool-that-writes-changelogs-for-you/", "title": "I Built a CLI Tool That Writes Changelogs For You — Here's Why", "summary": "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.", "date_modified": "2026-04-01T00:00:00.000Z", "author": { "name": "Faith Wachukwu", "url": "https://faithkovi.xyz" }, "tags": [ "changelog automation", "LLM", "AI tools for developers", "technical writing", "prompt engineering", "documentation engineering", "Google Gemini API", "LLM developer tools", "Keep a Changelog", "CI/CD automation" ] }, { "id": "https://faithwachukwu.com/blog/how-to-write-documentation-for-both-humans-and-ai-retrieval-systems/", "content_html": "![\"A](\"https://faithwachukwu.com/img/blog/cover-docs-humans-ai.png\")
\nYour 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.
\nThat means your documentation now serve two audiences: the person trying to solve a problem, and the machine trying to extract the right answer. In this post, you’ll learn how to write documentation that serves both the human and the AI retrieval systems.
\nHuman and AI retrieval systems function differently during information retrieval. A human can open a page with badly structured content, scan and find the specific information they came for. But for AI retrieval systems, if the information it’s looking for is in a different heading other than the heading it came for, it retrieves the wrong information. This impacts the quality of the output.
\nThis kind of documentation was written for linear reading, and these AI retrieval systems don’t work that way. Even for a human, that’s bad structure. This is why it's important to be deliberate about where answers to questions live in documentation.
\n![\"A](\"https://faithwachukwu.com/img/blog/excalidraw1.png\")
How RAG systems process your documentation: chunk, search, generate. The quality of the output depends on how well each chunk stands on its own.
When a reader opens a documentation page, they have a problem they want to solve. In doing that, they don’t want to read more than they have to. They need enough context to solve their problem.
\nGood documentation should explain ideas that build on each other. With headings, spacing, and code blocks in place, the mental effort needed to parse information is reduced. The Nielsen Norman Group's research on the inverted pyramid confirms what most tech writers already feel: people scan first and read second. They want to understand the core idea before the deep implementation.
\nThis principle is called progressive disclosure. You start with the simplest version of the explanation and gradually layer the complex parts. This reflects how people actually learn.
\nFor the chatbot or RAG tool, it’s a different ball game. It doesn’t start at the top and build understanding. It breaks your page into chunks, searches for the most relevant match to the query, and uses what it finds to generate a response. This means each section has to stand on its own. If a section depends on a context from three sections earlier, the retrieval system will respond without it, and the reader gets an incomplete answer.
\nRAG systems perform better when they receive self-sufficient sections with clear headings and consistent metadata that indicate what each page covers.
\nAn example is an engineer asking an AI assistant: “How do I roll back a failed deployment on Y?”
\nConsider these two versions of the documentation:
\n\n\nVersion A — Page title: Release Workflow. Section heading: Post-deployment considerations.
\nVersion B — Page title: Roll back a failed deployment. Section heading: How to roll back a deployment. Tags: deployment, rollback, >incident response.
\n
Version B makes it easy for both humans and machines to find the right answer.
\n![\"A](\"https://faithwachukwu.com/img/blog/comparison1.png\")
Same document, two completely different reading patterns. One reads linearly. The other grabs and runs.
Some best practices for human readers aren’t for AI retrieval systems. An example is progressive disclosure. Humans benefit from getting the context before the answer, and this feels natural. It’s like getting a good explanation from a colleague. But with AI retrieval systems, it doesn’t care about your buildup. It wants the answer straight up. If you lead with context and bury the solution four paragraphs down in an unrelated heading, the system would grab the preamble and miss the instructions.
\nLet’s say you’ve written a section on \"configuring retry policies\". A human reader would benefit from the first paragraph explaining why the retry policies matter. But for an AI retrieval system, it just needs: \"Set maxRetries to 3 and backoffMultiplier to 2.9 in your service config.” Looking at that, both readers need that information, but in a different order.
To make it serve them both, restructure each section so the answer comes first, followed by the context. Journalists have done this for over a century, and it’s called the inverted pyramid. The machine gets its clean answer while the human gets their narrative.
\nYou don’t need to rewrite everything. You should make these changes:
\nBefore you write any section, ask yourself: “What question is this section answering?”
\nThen drive at answering that question.\nWhen a section answers one question, the human readers can scan the table of contents and jump straight to what they need. The same goes for the AI retrieval system; it can match the section directly to the query without parsing unnecessary information.
The Diátaxis framework applies a similar principle at the page level, separating documentation into tutorials, how-to guides, reference, and explanation. This idea scales down to individual sections, too.
\n![\"Diataxis](\"https://faithwachukwu.com/img/blog/diataxis.png\")
The Diátaxis Framework
Writing vague headings forces the reader to open the section and scan through to decide if it’s relevant or not. They also make it nearly impossible for an AI retrieval system to match the section to a query.
\nThe Google developer documentation style guide recommends the use of task-based headings that describe what the reader will accomplish. This serves the AI retrieval systems just as well.
\nOpening every section with the answer is a high-impact change you can make. It’ll feel wrong at first, but for documentation, you aim to solve a problem and not write too much prose as you’d do in a novel.
\nOpen with the key ideas in the first sentence, then use the rest of the section to explain and give more context with examples. Your answer is now at the frontline. The human reader immediately knows they’re in the right place, and the AI retrieval system has the correct answer in the first chunk it grabs. This mirrors the inverted pyramid structure that's been the backbone of news writing since the telegraph era.
\nUsing phrases like “as configured in the previous section” might not work for AI retrieval systems. When adding code examples, include everything needed to understand or run the example right there, like the import statements, variable definitions, and configuration values. Yes, looks like repetition, but it’s worthwhile.
\nMetadata is the first thing search systems and AI retrieval systems use to decide whether your page is relevant. You could structure every section well, but none of it matters if readers can’t find your page in the first place. Metadata is what gets your documentation into the room.
\nHere's the same documentation written two ways.
\nBefore (traditional narrative structure):
\n\n\nWorking with Retry Policies
\nRetry policies are an important part of building resilient services. When a request fails due to a transient error, such as a network timeout or a temporary service outage, a retry policy determines whether and how the system attempts the request again.
\nThere are several factors to consider when configuring retries, including the maximum number of attempts, the delay between attempts, and whether to use exponential backoff.
\nTo configure a retry policy, set
\nmaxRetriesto 3 andbackoffMultiplierto 2.0 in your service configuration file.
A retrieval system grabbing the first paragraph gets a general explanation with zero actionable content. The actual instruction is buried at the bottom.
\nAfter (structured for both readers):
\n\n\nHow to Configure a Retry Policy for Transient Failures
\nSet
\nmaxRetriesto 3 andbackoffMultiplierto 2.0 in your service configuration file. This ensures failed requests are retried with increasing delays, preventing cascading failures.Retry policies handle transient errors like network timeouts and temporary outages. Without them, a single failed request surfaces as a user-facing error even when the issue resolves in milliseconds. Exponential backoff — doubling the wait between each retry — gives the downstream service time to recover without piling on additional load.
\n
This example shows they both have the same information and depth, except that in the second, the answer comes first. An AI retrieval system grabs the solution on the first pass. A human gets the answer immediately and reads on to understand why.
\nAnother example can be seen in this image below:
\n![\"Side-by-side](\"https://faithwachukwu.com/img/blog/chatbot-bad-vs-good.png\")
The difference between a useless chatbot response and a helpful one often comes down to where the answer sits in the section
To make your documentation fit for both human and AI retrieval systems, don’t overhaul everything at once. Pick your most visited page and start from there. Audit it against these five rules. Restructure it and watch whether the AI retrieval systems and engineers get better answers. Then do the next page. Teams that structure documentation for both the human and machine readers are building knowledge bases that actually scale.
", "url": "https://faithwachukwu.com/blog/how-to-write-documentation-for-both-humans-and-ai-retrieval-systems/", "title": "How to Write Documentation for Both Humans and AI Retrieval Systems", "summary": "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.", "date_modified": "2026-03-26T00:00:00.000Z", "author": { "name": "Faith Wachukwu", "url": "https://faithkovi.xyz" }, "tags": [ "technical-writing", "documentation", "AI", "RAG", "developer-experience", "content-strategy", "LLM" ] }, { "id": "https://faithwachukwu.com/blog/writing-for-the-engineer-who-will-replace-you/", "content_html": "![\"An](\"https://faithwachukwu.com/img/blog/cover-writing-engineer.jpg\")
\nYou’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.
\nAs 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.
\nWhen starting a new role or in your current role, you might think your colleagues might not need your docs. And yes, that’s right, they might not. I mean, they were in the same Slack threads and meetings. They were there when someone made a questionable decision on the infrastructure on a Friday.
\nYour real audience is the person who is employed 18 months later, handed the workload and is told, “You own this now.” With no context, no Slack history, and no memory of what has happened previously that shaped how the systems work today. All they have is what was left behind.
\nInitially, at the start of my career in DevOps, I would document things I did by writing things clearly. Well, it became useless six months down the line when the steps had changed. I didn’t go back to update the document.
\nKnowing the reason why decisions were made is important in documentation. Beyond writing out the steps of actions taken, you should know the context behind decisions to understand the why, instead of following what you don’t understand. This could be as simple as two sentences, not like a full-blown write-up, and it can save someone the time and financial cost due to a mistake.
\nWhen you’re on call, you know there is a difference between reading documentation to find out how a tool works versus reading it when there is downtime, and you are getting pinged nonstop. At that moment, you’re a different reader. One who is not interested in how it was written, you just want answers fast. You’d want to know:
\nSo when you’re structuring anything operational, keep that person in mind. Make sure you use short sentences, clear headings, and remove what would create doubt in their minds. If there’s a command they’ll need to run, include it, make it visible and easy to find and not buried deep into a paragraph section.
\nTreating your documentation as a product, not a side work, is a shift you should make. Think about it this way: if the person replacing you can’t understand the system from your documentation, then you haven’t finished working on that documentation.
\nWhen you see documentation as a product that has users, a purpose, and a quality standard to follow, you start making different choices. You’ll think about the structure, what is important to add or leave out, and how to maintain it.
\n![\"A](\"https://faithwachukwu.com/img/blog/writingEngineer2.png\")
A simple workflow diagram of documentation lifecycle
With the mindset of seeing documentation as a product, you’d document the state of things for every system you own. Mention what works well, what’s been held together by strings, and if there are potential risks in the systems.
\nIf you had to dig through 3 Jira tickets and a Slack thread to figure something out that is needed, then it’s a sign you should document it. The fact that it was hard to find means someone will face the same issue. It’s easier to revisit docs than to dig through Slack threads.
\nIn cases where there were recent additions or something was confusing in a runbook you own, correct it right then and not later. That’s because the next person who’ll read it won’t have context to know there is a problem. They’ll trust it blindly.
\nAdditionally, write like a human. Use “we” and “you” occasionally. When something is genuinely confusing, you’d say, “This is confusing, but here’s the deal”. Don’t pretend everything works perfectly when it doesn’t. Writing honestly in documentation helps to build trust, even with someone you’ll never meet.
\nAt the end, everything you’ll build, configure, or every shortcut you’ll take to implement things will be inherited by someone else. The quality of the documentation you leave behind says something about you as a professional.
\nLeave brilliant documentation handoffs to the next person. Brilliant, not in the sense of perfect documentation, but documentation that is written with the next person in mind. Let it be written clearly with the necessary information. This leaves a trail that says, “I cared about whoever came after me.”
", "url": "https://faithwachukwu.com/blog/writing-for-the-engineer-who-will-replace-you/", "title": "Writing for the Engineer Who Will Replace You", "summary": "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.", "date_modified": "2026-03-09T00:00:00.000Z", "author": { "name": "Faith Wachukwu", "url": "https://faithkovi.xyz" }, "tags": [ "devops", "docs" ] }, { "id": "https://faithwachukwu.com/blog/what-makes-api-documentation-work/", "content_html": "![\"What](\"https://faithwachukwu.com/img/blog/apidocswork.jpg\")
\nSome 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.
\nFor developers, their experience in the first few minutes of opening the documentation shapes their outlook on the API. This often determines if they continue exploring how to use the API or move to a different alternative.
\nIn effective documentation, there is a clear path from account creation to making your first successful API request. The focus is on helping developers achieve their first win rather than pushing technical details in their faces.
\nStripe, for example, provides dedicated getting started resources, SDK installation instructions, testing guides, and integration tools that can help developers build things quickly.
\nA clear getting started guide should answer the following questions immediately:
\nWhen developers find these answers within minutes, it becomes easier for them to adopt the API.
\nFor developers, they learn by doing. There is no amount of descriptive text that can replace a working code example. To create effective documentation, you should include examples that demonstrate real-world cases. The examples should be complete enough to copy, run, and modify.
\nA good example is Twilio’s documentation that includes multi-language code examples to help developers understand how to implement across different environments.
\n![\"A](\"https://faithwachukwu.com/img/blog/twilio-multilang.png\")
A multi-language code example in the Twilio API docs
Good examples normally:
\nResearch on API documentation has also shown that developers place significant value on practical usage scenarios and examples when learning about new APIs.
\nIn API documentation, guides help developers get started, but with references, they can build production applications.\nA good API reference should clearly document:
\nStripe's API reference is a strong example of this approach. It provides predictable resource structures, request formats, authentication guidance, testing information, and error-handling documentation in a consistent format.
\nFor these references, completeness matters because developers frequently rely on references while troubleshooting. When there are missing parameters or unclear error responses, it can lead to frustration.
\n![\"Error](\"https://faithwachukwu.com/img/blog/stripe-error-page.png\")
Error codes page in Stripe API docs
Even with the best content, if developers cannot find it, it becomes ineffective. Your documentation should be organized around the user’s goals rather than how the internal product is structured. The navigation should make it easy to move between tutorials, guides, API references, troubleshooting resources, and changelogs.
\nDevelopers can easily identify poor navigation in your documentation and weak search experiences.\nGood documentation sites should make it easy to answer questions such as:
\nHow quickly the developers can find the answers they are looking for leads to the likelihood of trusting the documentation.
\nDocumentation should be viewed as a product that requires continuous maintenance.
\nHaving outdated examples, deprecated SDK references, and inaccurate endpoint information will create confusion and increase support costs. Developers can judge how reliable an API is by the reliability of its documentation.
\nTop API providers invest heavily in versioning, changelogs, and regular documentation updates. Stripe, for example, maintains versioning guidance, API upgrade documentation, and changelogs to help developers manage these changes over time. This means that maintaining documentation should be part of the development lifecycle.
\nUsing docs-as-code practices, automated reviews, and implementing documentation ownership models can help teams keep content accurate as the product evolves.
\nWhat makes API documentation work is its ability to help developers achieve their goals with minimal friction.\nGood documentation shares several characteristics: clear getting-started guides, practical examples, comprehensive references, excellent navigation, and consistent maintenance. Together, these characteristics transform the developer experience. When documentation helps the developers quickly, the API is easier to trust and adopt.
", "url": "https://faithwachukwu.com/blog/what-makes-api-documentation-work/", "title": "What Makes API Documentation Work?", "summary": "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.", "date_modified": "2025-10-15T00:00:00.000Z", "author": { "name": "Faith Wachukwu", "url": "https://faithkovi.xyz" }, "tags": [ "API documentation", "docs", "API", "technicalwriting" ] }, { "id": "https://faithwachukwu.com/blog/docs-and-deployments-the-power-of-clear-documentation-in-devops/", "content_html": "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.
\nFor 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.
\nBridging Communication Gaps
\nDevOps is about collaboration, but let’s be honest, there is a high chance that miscommunication can happen. When there is no proper documentation, tribal knowledge becomes the go-to for information, and teams end up wasting time trying to figure out processes instead of executing them.\nHaving well-documented deployment workflows removes guesswork and ensures everyone stays on the same page. So instead of relying on Slack messages and word-of-mouth explanations, teams can refer to a single source of truth to prevent errors.
Building Faster Onboarding and Stronger Knowledge Sharing
\nFor new team members, having a smooth transition into the team’s workflow is a huge task. Imagine having to rely on scattered notes or having endless back-and-forths with team members just to understand better how things are done. It would have been easier and faster if there were runbooks, workflow guides and system overviews readily available for new team members.
\nWith this, the dependency on senior engineers for answers reduces. Think of documentation as a self-serve knowledge base. When it is done right, it helps teams operate efficiently.
Enabling automation and standardization
\nDevOps thrives on automation, from CI/CD pipelines to infrastructure as code (IaC). Let’s be real, having automation in place without documentation is like chaos waiting to happen.
\nWhen scripts, configurations, and processes are documented, teams can:
For example, when you document Terraform modules or Ansible playbooks, everyone who comes across the document will get information to help them understand the infrastructure setup rather than blindly running scripts.
\nAn effective DevOps documentation cuts across various categories such as:
\nWhen creating documentation, ensure the information you add is useful and practical. Here are some best practices to keep in mind:
\nTo make documentation easier to create and maintain, DevOps teams can use:
\nVersion Control for Documentation
\nDocumentation Platforms
\nAutomation for Documentation Updates
\nTeams often face challenges that affect accuracy, consistency, collaboration, and long-term maintainability. Here are a few that are common:
\n“We don’t have time for documentation.”\nTo solve this, you have to make documentation a part of the workflow rather than waiting till the end. Ask for updates during sprint reviews or integrate them into pull requests.
\n“Documentation is inconsistent across teams.”\nMake sure you establish clear documentation standards and templates that teams can follow. This ensures consistency across all documentation.
\n“Keeping documentation updated is hard.”\nYou should assign ownership for key documents, track them, set review cycles to ensure they stay relevant, and automate updates where possible.
\nWhen it comes to documentation in DevOps, you shouldn’t treat it like an afterthought. It’s a core part of DevOps success. From bridging the communication gaps to enabling knowledge sharing, having good documentation helps drive efficiency and prevent costly mistakes.\nSo you should prioritize it in your workflows, keep it up-to-date, and you’d see how this improves your DevOps processes.
", "url": "https://faithwachukwu.com/blog/docs-and-deployments-the-power-of-clear-documentation-in-devops/", "title": "Docs and Deployments: The Power of Clear Documentation in DevOps", "summary": "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.", "date_modified": "2025-06-23T00:00:00.000Z", "author": { "name": "Faith Wachukwu", "url": "https://faithkovi.xyz" }, "tags": [ "devops", "docs", "docs as code", "documentation" ] }, { "id": "https://faithwachukwu.com/blog/how-diataxis-turns-documentation-chaos-into-clarity/", "content_html": "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.
\nInstead of following the pattern of following rigid rules and overwhelming plans. Diataxis offers you a refreshing approach: take things one step at a time, let the structure emerge naturally, focus on making small, meaningful improvements. The best part is that you don’t need to fully understand it before diving right into it. With Diátaxis, you learn by doing, taking small, meaningful steps to transform your docs into something clear.
\nDiátaxis, at its core, offers a complete picture of documentation without imposing rules that are too rigid. It’s more like a guide that helps you understand where your documentation is and where it needs to go. Unlike following the traditional way of prioritizing extensive planning, Diátaxis advocates for adaptability and incremental progress.
\nDiátaxis encourages writers to focus on small changes instead of striving for immediate perfection. Over time, with these improvements, the documentation shapes into more of a clear user-focused structure without forcing it into already predefined categories.
\nWhen writing following the traditional writing process, it’s often emphasized that you should start with a clear structure: divide the content into tutorials, how-to guides, reference materials, and explanations.
\nHowever, Diátaxis warns against this approach. Instead of creating empty sections for future content, which is counterproductive and frustrating, you should let the structure emerge naturally.
\nThis is done by addressing what the user needs at that specific time and improving the content piece by piece; then your documentation will organically align with the Diátaxis framework. This inside-out development makes sure the structure reflects well-formed content.
\nOne of Diátaxis’ key principles is iterative improvement. Even if your documentation feels like an unmanageable mess, there’s always a way forward by taking it one small step at a time. Here’s how to apply this method:
\nBy using this approach, you’ve reduced decision paralysis and progressed steadily. This keeps your documentation consistently aligned with what your users need.
\nDiátaxis likens documentation to a living organism, emphasizing well-formed organic growth. Just as a plant develops from a healthy seed into a mature tree, documentation evolves through iterative improvements at the “cellular” level, these include individual paragraphs, sentences, or sections.
\nWhen each component is carefully nurtured and improved, the overall structure emerges naturally, adapting to external conditions like user feedback and product updates. This type of growth fosters better, more resilient documentation.
\nA defining concept in Diátaxis is the difference between what is complete and what is finished. Documentation, like a living organism, is never truly finished because it must continuously evolve alongside the product and its users. However, it can always be completely useful, appropriate, and ready for its current stage of development.
\nImagine a plant at every stage of its life. From a seedling to a fully-grown tree, it is always complete in its own right, even as it continues to grow and mature. Documentation can follow the same principle: providing value to users at every stage while remaining open to future refinements.
\nImage of Diátaxis Framework
Diátaxis framework groups documentation into four distinct modes, each of which serves a specific purpose:
\nBy iterating on your content with these modes in mind, your documentation will naturally take on a shape that serves the diverse user needs.
\nApplying Diátaxis can feel counterintuitive at first, especially if you’re used to traditional documentation practices. Here are some practical tips to navigate common challenges:
\nDiátaxis transforms documentation from a complex task into a manageable, iterative process. By focusing on small, meaningful changes and allowing the structure to emerge organically, this approach empowers writers to produce user-centric, adaptable documentation. Whether starting from scratch or refining a chaotic documentation, Diátaxis offers the tools and principles to guide you toward clarity and success one step at a time.
\nUnderstand that with documentation, it’s not just a deliverable. Rather you should see it as a dynamic and evolving process. With Diátaxis, you can embrace the process with confidence that every small step contributes to a clearer, more effective documentation.
", "url": "https://faithwachukwu.com/blog/how-diataxis-turns-documentation-chaos-into-clarity/", "title": "How Diátaxis Turns Documentation Chaos into Clarity", "summary": "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.", "date_modified": "2025-01-08T00:00:00.000Z", "author": { "name": "Faith Wachukwu", "url": "https://faithkovi.xyz" }, "tags": [ "diataxis", "docs" ] } ] }