From 00e3b336f90eda37a46122b319c7b54099858f6b Mon Sep 17 00:00:00 2001 From: Claude Date: Thu, 12 Feb 2026 12:46:05 +0000 Subject: [PATCH] Add blog section with listing page and first blog post - Create blog.html listing page matching existing dark theme - Add first post: "Why Docs-as-Code Is the Only Way I Work Now" - Add Blog link to navigation on all pages (index, about, portfolio) - Update sitemap.xml with blog listing and post URLs - Include full SEO meta tags (Open Graph, Twitter Card) on blog pages https://claude.ai/code/session_01TSwbvsqV6K12wuKRsyUSvy --- about.html | 1 + blog.html | 216 +++++++++++++++++++++++++ blog/why-docs-as-code.html | 315 +++++++++++++++++++++++++++++++++++++ index.html | 1 + portfolio.html | 1 + sitemap.xml | 10 ++ 6 files changed, 544 insertions(+) create mode 100644 blog.html create mode 100644 blog/why-docs-as-code.html diff --git a/about.html b/about.html index 1be5f228..a13c2fcd 100644 --- a/about.html +++ b/about.html @@ -205,6 +205,7 @@
About Portfolio + Blog
diff --git a/blog.html b/blog.html new file mode 100644 index 00000000..3c7bbfd0 --- /dev/null +++ b/blog.html @@ -0,0 +1,216 @@ + + + + + + Blog | Favour Kelvin + + + + + + + + + + + + + + + + + + + + +
+

Blog

+

Thoughts on technical writing, documentation strategy, and what I've learned building docs for developer tools.

+ +
+ +

Feb 12, 2026

+

Why Docs-as-Code Is the Only Way I Work Now

+

After years of working in wikis, CMSes, and proprietary platforms, I switched to docs-as-code and never looked back. Here's what changed and why it matters.

+
+ docs-as-code + workflow + technical writing +
+ +
+
+ + diff --git a/blog/why-docs-as-code.html b/blog/why-docs-as-code.html new file mode 100644 index 00000000..161a4c4b --- /dev/null +++ b/blog/why-docs-as-code.html @@ -0,0 +1,315 @@ + + + + + + Why Docs-as-Code Is the Only Way I Work Now | Favour Kelvin + + + + + + + + + + + + + + + + + + + + + + +
+ ← All posts + +

Feb 12, 2026

+

Why Docs-as-Code Is the Only Way I Work Now

+
+ docs-as-code + workflow + technical writing +
+ +
+

I've written documentation in Confluence, Google Docs, Notion, proprietary CMSes, and wikis that required three logins to access. Every time, the same problems showed up: version control was a mess, reviews were slow, and the docs drifted out of sync with the product within weeks.

+ +

Then I started working with teams that treated documentation the same way they treated code. Markdown files in a Git repo. Pull requests for reviews. CI/CD pipelines for publishing. Everything changed.

+ +

What Docs-as-Code Actually Means

+ +

Docs-as-code isn't just "write in Markdown." It's a workflow where documentation lives alongside the codebase and follows the same development practices:

+ +
    +
  • Version control with Git, so every change is tracked and reversible
    • +
  • Pull request reviews, so engineers and writers can collaborate before anything goes live
    • +
  • Automated linting with tools like Vale to catch style issues, broken links, and inconsistencies
    • +
  • CI/CD pipelines that build and deploy docs on merge, keeping everything in sync with releases
    • +
  • Plain text formats like Markdown or MDX that work with any editor and don't lock you into a platform
    • +
+ +

Why It Works Better

+ +

The biggest advantage is that docs live where the code lives. When a developer changes an API endpoint, the documentation for that endpoint is in the same repo. The PR that changes the code can also update the docs. No context-switching to a separate tool. No "I'll update the docs later" tickets that never get done.

+ +

Reviews are faster because engineers already know how pull requests work. They don't need to learn a new tool or figure out commenting in some wiki platform. They read the diff, leave comments, and approve. The same workflow they use for code.

+ +

Linting catches problems automatically. When I set up Vale with a custom style guide, every PR gets checked for passive voice, jargon, inconsistent terminology, and broken links before a human even looks at it. That means reviews can focus on accuracy and clarity instead of catching typos.

+ +

The Tools I Use

+ +

My typical setup looks like this:

+ +
    +
  • Markdown or MDX for content
    • +
  • Git + GitHub for version control and reviews
    • +
  • Docusaurus, Mintlify, or Nextra for the documentation site
    • +
  • Vale for style linting
    • +
  • GitHub Actions for CI/CD
    • +
+ +

The specific static site generator depends on the team's needs. Docusaurus works well for larger doc sites with versioning. Mintlify is great when you want something polished with minimal config. Nextra is a good choice if the team is already in the Next.js ecosystem.

+ +

When It Doesn't Work

+ +

I won't pretend docs-as-code is always the answer. If the people writing documentation aren't comfortable with Git, the learning curve can slow things down. Some teams have non-technical writers who are faster in a CMS. That's fine.

+ +

But for developer documentation specifically, where the audience is developers and the content needs to stay tightly coupled with a codebase that's changing fast, I haven't found anything better.

+ +

The Real Win

+ +

The real win isn't any single tool or practice. It's that documentation stops being an afterthought. When docs are in the same repo, reviewed in the same workflow, and deployed in the same pipeline, they become part of the product. Not something bolted on after the fact.

+ +

That's the shift. And once you've worked that way, it's hard to go back.

+
+ +
+

Want to chat about docs-as-code or technical writing? Reach out on LinkedIn or email me.

+
+
+ + diff --git a/index.html b/index.html index 07430b47..34d7bcff 100644 --- a/index.html +++ b/index.html @@ -170,6 +170,7 @@
diff --git a/portfolio.html b/portfolio.html index 1f16dae7..e782ec66 100644 --- a/portfolio.html +++ b/portfolio.html @@ -105,6 +105,7 @@
About Portfolio + Blog
diff --git a/sitemap.xml b/sitemap.xml index 3900f6ca..2233e859 100644 --- a/sitemap.xml +++ b/sitemap.xml @@ -15,4 +15,14 @@ monthly 0.9 + + https://fakela.github.io/blog.html + weekly + 0.8 + + + https://fakela.github.io/blog/why-docs-as-code.html + yearly + 0.7 +