Forem: DanielleWashington

Audit Your Docs Against The Decision-System Framework

DanielleWashington — Mon, 30 Mar 2026 01:56:59 +0000

Audit Your Docs Against the Decision-System Framework

Most documentation fails not because something is missing, but because it answers the wrong question.

We've built encyclopedias when people need guides. We've cataloged every possible path when what readers actually need is someone to say: start here, this way works. The result is what I call the library paradox. All the information exists, users just can't find their way to the answer that matters for their specific situation at this specific moment. The problem isn't missing information. The problem is missing navigation.

doc-audit is a CLI tool that operationalizes this. It scans your markdown files, classifies each one by decision phase, scores how well it guides a reader toward action, and gives you a prioritized list of what to fix. This post walks through how to use it and how to think about what it's telling you.

The framework

Every person who arrives at your documentation is standing at a crossroads. They're not asking "what does this do?" They're asking "what should I do, given my constraints, right now?" That's a decision, not a knowledge transfer. Decisions require navigation, not encyclopedias.

The Day 0/1/2 framework maps the decision landscape across the full adoption lifecycle.

Day 0, Pre-Commitment. The reader hasn't adopted your tool yet. They're evaluating: is this right for my use case? What am I signing up for? What are the tradeoffs I should understand before I commit? Think of this as the moment before buying hiking boots. You need to know if you're going on day hikes or through-hiking the Appalachian Trail. The boots you need are different. If your docs skip this phase, you're losing people before they ever install anything.

Day 1, Getting Started. The reader has committed. They want the fastest path from zero to working state. They need a clear sequence, a default configuration that fits most cases, and a success signal at the end. This is base camp. Get the tent up, get oriented, don't try to summit on your first day.

Day 2, Production. The reader is past the happy path. Something broke, or they're scaling, or conditions changed. They need troubleshooting guides, operational runbooks, and explicit "if X is happening, do Y" callouts. Day 2 readers are not reading for pleasure on a Sunday morning. They're in the moment of crisis and they need the answer fast.

Each phase has its own decision architecture. Mapping these explicitly is what turns a documentation suite from an information dump into a navigation system.

The framework maps the human reader's journey, but your docs now have a second audience that moves through that same content completely differently.

There's a second dimension the tool measures: whether your docs are written for both audiences now consuming them. Your human reader and an agent acting on their behalf have fundamentally different needs. Humans can ask follow-up questions, fill in gaps with context, probe for answers they didn't know they needed. Agents cannot. They fill gaps not with judgment but with hallucination. A document with clear decision points, explicit next steps, and no assumed context serves both.

Run this against your own docs

Node.js 18 or higher.

git clone https://github.com/DanielleWashington/doc-audit
cd doc-audit
npm install

To use the doc-audit command anywhere:

npm link

Verify it:

doc-audit --help

Step 1: Run the audit

Point doc-audit at any directory containing .md files. The bundled sample docs are a good place to start:

node index.js ./test-docs

This launches interactive mode. Before any prompts appear, doc-audit has already analyzed every file. The interview that follows lets you review and correct that analysis.

What the static analysis does

doc-audit reads each file and runs signal matching against three dictionaries.

Day 0 signals look for evaluation language: overview, why use, compare, alternatives, when to use, who is this for. Day 1 signals look for onboarding language: install, quickstart, tutorial, getting started, how to, prerequisites. Day 2 signals look for operational language: troubleshoot, debug, error, production, failing, incident, rollback.

The phase with the most matches wins. This isn't perfect. A file titled quickstart.md could have Day 2 content, which is exactly why the interview step exists.

Alongside phase detection, each file gets a quality score out of 8. Six signals are checked:

Signal	Points	What it measures
If/then guidance	2	`if ... then/→/do/try/run` patterns, the clearest marker of decision-oriented writing
Tradeoff language	2	"when not to", "limitation", "⚠", "not recommended", does it help users see around corners?
Ordered steps	1	Numbered lists signal a sequence to follow
Learning outcome	1	"by the end", "you will learn", sets expectations and helps readers self-select
Next steps	1	"next steps", "proceed to", does it hand the reader off somewhere?
Focused length	1	Under 1,000 words. Docs that try to serve all three phases usually serve none well

The if/then and tradeoff signals carry double weight because they're the hardest to fake. A doc can have ordered steps and a next steps section and still be a knowledge dump. A doc with explicit "if your use case is X, do Y, if it's Z, consider this instead" language has crossed into decision-oriented territory. That's the difference between a map and turn-by-turn directions.

The interactive interview

For each file, you'll see its detected phase, quality score, and a short prompt:

──────────────────────────────────────────────────
  api-reference.md
  892 words  ·  Auto-detected: Day 1 — Getting Started
  Decision quality: 2/8
──────────────────────────────────────────────────

? What do you want to do with this file?
❯ Audit it
  Skip it
  Flag for deletion

Action. Skip excludes the file from the report, useful for auto-generated files, changelogs, or anything that shouldn't be part of the audit. Flag for deletion marks it as a candidate for removal, shown separately in the report. Choose Audit it to continue.

Phase confirmation. Correct the auto-detected classification here. An api-reference.md might have been tagged as Day 1 because it mentions how to use, but it's actually a reference doc that spans all three phases. Fix it.

Decision quality. You're asked whether the doc recommends a clear path, presents options but leaves the decision to the reader, or mostly describes without guiding action. Be honest. This is the distinction the whole framework turns on.

If/then and next step. Two quick yes/no confirmations that override the static analysis when your judgment differs from the regex.

Step 2: Read the report

╔═══════════════════════════════════════════════════════╗
║  doc-audit Report                                     ║
║  /projects/my-tool/docs                               ║
╚═══════════════════════════════════════════════════════╝

PHASE COVERAGE
  Day 0  ██░░░░░░░░   1 of 4    ⚠ Undercovered
  Day 1  ██████░░░░   2 of 4    ✓
  Day 2  ░░░░░░░░░░   0 of 4    ✗ Missing

DECISION QUALITY (avg: 3.8/8)
  ✓ quickstart.md                  6/8  — Strong decision doc
  ⚠ overview.md                    4/8  — Partially decision-oriented
  ✗ api-reference.md               2/8  — Knowledge dump
  ✗ architecture.md                3/8  — Knowledge dump

RECOMMENDATIONS
  1. Missing Day 2 content — add a troubleshooting or production guide
  2. api-reference.md — low decision quality. Add "If X → do Y" callouts...
  3. architecture.md — no If/then guidance detected...

Phase Coverage is the structural view. A missing phase means readers at that stage of the adoption lifecycle have nothing to reach for. This is where the pattern shows up every time: Day 1 coverage is solid, Day 0 is weak, Day 2 is almost entirely absent. Teams onboard users and then abandon them in production.

Decision Quality is the per-file view. Knowledge dump means the file explains things but doesn't help the reader decide or act. Strong decision doc means it has explicit guidance, surfaces tradeoffs, and ends by pointing somewhere.

Recommendations are prioritized. Phase gaps come first because they're the largest structural problem. Per-file findings follow.

Step 3: Auto mode and exports for CI

For CI or fast trend-tracking, use auto mode:

doc-audit ./docs --auto

No prompts, static analysis only. Useful for catching regressions: a phase that was covered last sprint but isn't now, or an average quality score that's drifting down as docs accumulate.

To capture results for downstream processing:

doc-audit ./docs --json > audit.json

Pipe it into a script that fails CI if a phase is missing or the average quality score drops below your threshold.

For a shareable written record:

doc-audit ./docs --output docs-audit-march.md

Step 4: Act on what you find

Missing Day 0 content. Write a document that explicitly answers "should I use this?", covering what problem it solves, what it's not good for, and how it compares to the obvious alternatives. End it with a decision branch. If your use case is X, proceed to the quickstart. If it's Y, you might want Z instead. Give the reader somewhere to go either way.

Missing Day 2 content. Mine your issue tracker, Slack history, or support queue for the five most common things that go wrong. For each one, write an if X is happening → do Y entry. Day 2 readers are in crisis mode. A doc without explicit structure forces both the human reader and any agent acting on their behalf to fill the gap themselves, and agents fill gaps with hallucination.

Low quality score on an existing doc. The fastest fix is adding if/then guidance. Find every place the doc describes a choice and make it explicit: if you're using PostgreSQL, use the connection pool strategy. If you're on SQLite, skip this section entirely. One well-placed callout can move the score significantly.

Partially decision-oriented docs. These present options but hedge on recommending one. Sometimes that's appropriate, context genuinely varies. But often it's just that no one has committed to a recommended path. If that's the case, commit. Move the edge cases into a collapsible section. Surface the tradeoffs explicitly. Providing a framework where you can't be prescriptive is still better than leaving the reader at a crossroads with no guidance.

Where to start

If running this against a large docs suite feels overwhelming, start with your highest-traffic pages. Ask one question for each: what decision does this doc help a reader make? If you can't answer that in one sentence, that's your signal. You don't need to rewrite everything. Tightening the scope of a page to serve one phase, one decision, and one next step is usually enough to move it from Knowledge dump to Partially decision-oriented.

The goal isn't comprehensive coverage measured by word count. It's whether users can move from uncertainty to confident action with minimal friction. Documentation that does that is a growth lever. Documentation that doesn't generates support tickets asking "should I use X or Y?" for questions the docs technically answered but never resolved.

Run the audit. Fix the phase gaps. Add the if/then guidance. Run it again.

The docs that actually move people forward were never the most comprehensive ones. They were the ones that knew which question the reader was standing in front of, and answered it

Built on the documentation framework by Danielle Washington: Documentation is a Decision System, Not a Knowledge Base and The Documentation Framework We Need Doesn't Exist Yet.

Try the web app here

Audit Your Docs Against The Decision-System Framework

DanielleWashington — Mon, 30 Mar 2026 01:56:59 +0000

Audit Your Docs Against the Decision-System Framework

Most documentation fails not because something is missing, but because it answers the wrong question.

The framework

The Day 0/1/2 framework maps the decision landscape across the full adoption lifecycle.

Each phase has its own decision architecture. Mapping these explicitly is what turns a documentation suite from an information dump into a navigation system.

The framework maps the human reader's journey, but your docs now have a second audience that moves through that same content completely differently.

Run this against your own docs

Node.js 18 or higher.

git clone https://github.com/DanielleWashington/doc-audit
cd doc-audit
npm install

To use the doc-audit command anywhere:

npm link

Verify it:

doc-audit --help

Step 1: Run the audit

Point doc-audit at any directory containing .md files. The bundled sample docs are a good place to start:

node index.js ./test-docs

This launches interactive mode. Before any prompts appear, doc-audit has already analyzed every file. The interview that follows lets you review and correct that analysis.

What the static analysis does

doc-audit reads each file and runs signal matching against three dictionaries.

The phase with the most matches wins. This isn't perfect. A file titled quickstart.md could have Day 2 content, which is exactly why the interview step exists.

Alongside phase detection, each file gets a quality score out of 8. Six signals are checked:

Signal	Points	What it measures
If/then guidance	2	`if ... then/→/do/try/run` patterns, the clearest marker of decision-oriented writing
Tradeoff language	2	"when not to", "limitation", "⚠", "not recommended", does it help users see around corners?
Ordered steps	1	Numbered lists signal a sequence to follow
Learning outcome	1	"by the end", "you will learn", sets expectations and helps readers self-select
Next steps	1	"next steps", "proceed to", does it hand the reader off somewhere?
Focused length	1	Under 1,000 words. Docs that try to serve all three phases usually serve none well

The interactive interview

For each file, you'll see its detected phase, quality score, and a short prompt:

──────────────────────────────────────────────────
  api-reference.md
  892 words  ·  Auto-detected: Day 1 — Getting Started
  Decision quality: 2/8
──────────────────────────────────────────────────

? What do you want to do with this file?
❯ Audit it
  Skip it
  Flag for deletion

If/then and next step. Two quick yes/no confirmations that override the static analysis when your judgment differs from the regex.

Step 2: Read the report

╔═══════════════════════════════════════════════════════╗
║  doc-audit Report                                     ║
║  /projects/my-tool/docs                               ║
╚═══════════════════════════════════════════════════════╝

PHASE COVERAGE
  Day 0  ██░░░░░░░░   1 of 4    ⚠ Undercovered
  Day 1  ██████░░░░   2 of 4    ✓
  Day 2  ░░░░░░░░░░   0 of 4    ✗ Missing

DECISION QUALITY (avg: 3.8/8)
  ✓ quickstart.md                  6/8  — Strong decision doc
  ⚠ overview.md                    4/8  — Partially decision-oriented
  ✗ api-reference.md               2/8  — Knowledge dump
  ✗ architecture.md                3/8  — Knowledge dump

RECOMMENDATIONS
  1. Missing Day 2 content — add a troubleshooting or production guide
  2. api-reference.md — low decision quality. Add "If X → do Y" callouts...
  3. architecture.md — no If/then guidance detected...

Recommendations are prioritized. Phase gaps come first because they're the largest structural problem. Per-file findings follow.

Step 3: Auto mode and exports for CI

For CI or fast trend-tracking, use auto mode:

doc-audit ./docs --auto

No prompts, static analysis only. Useful for catching regressions: a phase that was covered last sprint but isn't now, or an average quality score that's drifting down as docs accumulate.

To capture results for downstream processing:

doc-audit ./docs --json > audit.json

Pipe it into a script that fails CI if a phase is missing or the average quality score drops below your threshold.

For a shareable written record:

doc-audit ./docs --output docs-audit-march.md

Step 4: Act on what you find

Where to start

Run the audit. Fix the phase gaps. Add the if/then guidance. Run it again.

The docs that actually move people forward were never the most comprehensive ones. They were the ones that knew which question the reader was standing in front of, and answered it

Built on the documentation framework by Danielle Washington: Documentation is a Decision System, Not a Knowledge Base and The Documentation Framework We Need Doesn't Exist Yet.

Try the web app here

The Documentation Framework We Need Doesn't Exist Yet

DanielleWashington — Tue, 24 Mar 2026 01:41:15 +0000

We can no longer write exclusively for a human audience, someone who reads carefully, asks follow-up questions, and fills in gaps with context and common sense.

I've bet you've seen it everywhere: "your docs need to be readable for agents." Agents, agents, agents, cue the Brady Bunch theme. Everyone is talking about agents taking technical writing jobs, AI this, AI that. But where are the actual solutions?

The technical writing industry has changed. We can no longer write exclusively for a human audience, someone who reads carefully, asks follow-up questions, and fills in gaps with context and common sense. Our docs now have a second audience. One that doesn't probe for answers, that doesn't ask for clarification, and fills gaps not with judgment but with hallucination.

The audience is agents. And we need to start writing for them.
Honestly, who actually wants to read pure reference documentation? If this → then that. Condition met → execute action. Technically precise and completely soulless.

The Diataxis framework has served us well, tutorials, how-to guides, reference, explanation. Clean separations, clear purposes. But it was built for human readers with patience and context. It wasn't built for agents. And it wasn't built for the developer at 11pm with a production issue who doesn't have time to wade through four pages of deployment documentation praying the answer is somewhere in there.

Most developers aren't reading docs on a Sunday morning for pleasure. They're reading because something is broken. So are we writing for the moment of curiosity or the moment of crisis? And now that agents are in the mix, consuming our docs to make decisions on behalf of that same frustrated developer, the question gets sharper.

What’s the bridge between barebones and overly informative?

What does great documentation actually do? To me, it answers the questions you hadn't thought to ask yet. The ones you didn't know you needed until you were already stuck.

An agent cannot ask follow up questions. It cannot pause mid-task and realize it needs more context. It cannot intuit that the edge case you didn't document is the one it's about to hit. It will simply proceed and fill the gap with its best guess, which is another word for hallucination.

Documentation that already anticipates the unasked question serves both readers. The human who didn't know what they didn't know. And the agent that cannot know what it wasn't told.

The goal has never been "write for humans" or "write for agents." The goal was always to write for the moment before the question forms.
We just didn't know we needed to say that out loud until now.

So what does this actually look like in practice?

Start here: before you write a single word, ask yourself two questions. What decisions are people reading this doc trying to make? And what will their likely next step be?
Not "what information do I need to convey?" That's the old question. That's how you end up with four pages of similarly named documentation that answers everything except the thing the reader actually needed.

The new question is about decisions and momentum. Where is this person trying to go? What do they need to know to get there? And what comes after that?

Something shifts when you write from that vantage. The document stops being a repository and starts being a guide. A guide with clear decision points, explicit next steps, and no assumed context is something both a human and an agent can actually use.

The decision your reader is trying to make isn't static. It changes depending on where they are in their journey.
Day 0 is testing. Day 1 is production. Day 2 is maintenance. Three stages, three completely different goals, three completely different things a developer, or an agent acting on their behalf, actually needs from your documentation.

A Day 0 developer needs to know if your product does what they think. A Day 1 developer needs to know exactly what to do and what happens if they get it wrong. And a Day 2 developer already knows your product but they're reading because something changed or something broke and they need the answer fast.

Trying to write the same doc for all three and you've literally wasted everyone’s time.

So where do you start?

Here’s three things you can do tomorrow:

Audit your existing docs and ask one question for each one: Why would a reader click on this page? What decision does this doc help a reader make? If you can't answer that in one sentence, that’s a signal that you need to tighten the scope of the page.
Identify which stage your reader is in. Are they Day 0, Day 1, or Day 2? Write to that stage's specific goal, not all three at once. A developer testing your product and a developer maintaining it in production are not the same reader. Stop writing like they are.
If possible, end every section with an explicit next step. Not a "see also" or a list of related articles. If X → do Y. Give both your human reader and any agent acting on their behalf a clear path forward.

The conversation about agent-readable documentation isn't going away. But talking about it without changing how we actually write is just noise.

We now have somewhere to start.

When Docs Meet Tools: The EKS Configurator Story

DanielleWashington — Mon, 02 Feb 2026 15:56:40 +0000

Note: This tool was never officially released. The day I was scheduled to demo it to our wider engineering team, restructuring happened—affecting me. This post is my way of giving the work the light of day it deserves. The tool is live at the link below, built through countless iterations and hard-won lessons about what makes developer tooling actually useful.

The Documentation Paradox

I was drowning in my own documentation. As a technical documentation writer on the Weaviate developer education and experience team, I'd spent months writing comprehensive guides about deploying our vector database on EKS. Configuration guides, best practices, security recommendations, networking tutorials—all meticulously crafted, reviewed, and published. Yet the support tickets kept climbing.

"How do I configure my node groups for Weaviate?"

"What instance types should I use for vector indexing workloads?"

"My Weaviate pods keep getting evicted—what am I doing wrong?"

"Can someone just tell me what YAML I need?"

The pattern was clear: developers weren't struggling because the information didn't exist. They were struggling because assembling that information into a working Weaviate deployment on EKS was overwhelming.

I needed to find a better way.

The Problem: When Complexity Meets Choice

Amazon Elastic Kubernetes Service (EKS) is powerful, but that power comes with complexity—especially when you're deploying a stateful, memory-intensive application like Weaviate. A production-ready EKS cluster for Weaviate requires decisions across multiple dimensions:

Infrastructure: Node groups, instance types (memory-optimized vs compute-optimized), scaling policies for vector workloads
Storage: EBS volume types (gp3 vs io2), provisioning for HNSW indices, persistent volume configurations
Networking: VPC configuration, subnets, security groups, CNI plugins, service mesh considerations
Security: IAM roles for S3 backups, RBAC policies, pod security standards, encryption at rest
Observability: Prometheus metrics for query performance, CloudWatch integration, distributed tracing
Add-ons: CoreDNS, kube-proxy, VPC CNI, EBS CSI driver, cluster autoscaler

And here's where it gets tricky for Weaviate deployments: each decision influences others in ways specific to vector database workloads.

Choose r6i memory-optimized instances? You'll need specific EBS volume configurations to match IOPS requirements for HNSW indexing.
Enable multi-tenancy? Your RBAC and network policies need to isolate tenant data.
Planning for horizontal scaling? You need StatefulSets with headless services and proper pod disruption budgets.
Using S3 for backups? You'll need IAM roles with specific permissions attached to service accounts via IRSA (IAM Roles for Service Accounts).

I'd written comprehensive documentation covering each topic. We had guides on:

Selecting instance types based on vector dimensionality and dataset size
Configuring persistent storage for optimal HNSW performance
Setting up monitoring for query latency and indexing throughput
Implementing backup strategies with S3 integration

But developers still needed to:

Read multiple scattered pages across Weaviate docs and AWS documentation
Understand how EKS, Kubernetes, and Weaviate-specific requirements interact
Translate conceptual knowledge into correct YAML manifests
Size their cluster appropriately for their specific vector workload
Validate their choices against best practices
Troubleshoot when combinations didn't work (and they often didn't)

I was asking people to become experts in EKS, Kubernetes storage, vector database performance characteristics, AND AWS networking just to deploy Weaviate. That's unreasonable.

The Inspiration: Learning from Competitors and Our Own Tools

Then I saw something that shifted my thinking. One of our competitors had built a configuration and sizing tool for their vector database. It asked questions about dataset size, query patterns, and performance requirements, then recommended hardware specifications and configuration settings. It wasn't perfect, but users loved it.

Around the same time, I was looking at Weaviate's existing Docker Configurator—a tool that helped users generate docker-compose.yml files for local development. It worked beautifully for getting developers started quickly without drowning them in documentation.

The connection clicked: What if I built something similar for EKS deployments?

This wouldn't just be nice to have—it could be a competitive differentiator. If our competitor could help users size their infrastructure, why couldn't we help them configure an entire production-ready EKS cluster specifically optimized for Weaviate?

The Realization: Documentation Has Limits

After analyzing support patterns and seeing what worked elsewhere, I had an uncomfortable realization: some concepts resist text-based explanation.

When configuration involves:

Multiple interdependent choices (changing instance type affects storage IOPS, which affects indexing performance, which affects scaling decisions)
Context-dependent recommendations (a semantic search application has different requirements than a recommendation engine)
Complex syntax (Kubernetes YAML that must be precisely correct, plus Helm values, plus AWS-specific annotations)
Validation requirements (certain combinations are invalid or suboptimal for vector workloads)
Domain-specific expertise (understanding both EKS operations AND vector database performance characteristics)

...traditional documentation struggles. I could write it, but developers couldn't easily apply it.

I needed a different approach.

The Hypothesis: Show, Don't Just Tell

What if instead of explaining all the configuration possibilities, I guided developers through making the right choices for their specific Weaviate deployment?

What if the tool could:

Ask contextual questions about their vector search use case
Recommend instance types based on vector dimensionality and dataset size
Explain options inline, right when decisions are made
Validate combinations specific to Weaviate workloads in real-time
Generate correct, tested EKS and Weaviate configuration automatically

This wouldn't replace my documentation—it would integrate with it, creating a complementary experience. Just like our Docker Configurator worked alongside our Docker deployment docs.

Building the EKS Configurator

I built the EKS Configurator as an interactive tool that bridges the gap between documentation and implementation.

Design Principles

I needed this tool to feel natural, not like another form to fill out. Here's what guided my design:

Context-Aware Guidance for Weaviate Workloads

The tool knows Weaviate-specific context that generic EKS docs can't anticipate.

Actionable Output

I generate complete, ready-to-use configurations:

eksctl cluster configuration YAML
storage-classes configuration templates for EBS volumes.

No translation layer—just copy, customize if needed, and deploy.

The Technical Stack

I chose Streamlit for rapid development. As a self-taught developer and technical writer, I needed something I could iterate on quickly without wrestling with frontend frameworks. Streamlit's Python-based approach let me focus on the logic and user experience.

The architecture:

Input Layer:

Streamlit forms and widgets capture user requirements
Session state management keeps track of choices across pages
Conditional rendering shows/hides options based on context

Decision Engine:

Python logic validates combinations and applies AWS best practices
Weaviate-specific sizing calculations (memory = vectors × dimensions × 4 bytes × safety factor)
Decision trees map use cases to optimal configurations

Template Generation:

eks-cluster-config
storage-classes for EBS volumes

The key technical challenge was balancing flexibility with simplicity. I didn't want to expose every possible EKS configuration parameter, but I needed enough options for real-world use cases.

Another challenge: keeping generated YAML valid. I wrote validators that check:

Required fields are present
Values match expected types and formats
Kubernetes resource names follow naming conventions
Storage sizes are appropriate for instance types
Memory requests don't exceed node capacity

The tool makes it feel less like filling out a form and more like consulting with a Weaviate deployment expert.

Iteration Through Feedback

The first version was... imperfect. I learned quickly through user feedback and support ticket patterns:

Too Many Options

My first iteration tried to expose every possible EKS configuration option because I wanted to be comprehensive. Users were paralyzed by choice.

I was recreating the documentation problem in tool form.

I learned to provide sensible defaults based on environment type, with the ability to customize when needed. Most users just needed to specify their workload characteristics—the tool could infer the rest.

One-Size-Fits-All

My first templates assumed everyone wanted production-ready configurations with high availability, monitoring, and security hardening. But some users just needed a quick dev environment to test Weaviate features. Others needed proof-of-concepts with minimal costs.

The Impact

Honestly, I didn't expect the impact to be significant, but internally the signals were clear - this tool would be helpful for our community users.

Personal Win:

The tool became a differentiator, not just a helper—exactly what I'd hoped when I first saw our competitor's sizing tool.

The tool and documentation became complementary, each strengthening the other. The tool didn't replace my docs; it made them more accessible and actionable.

Lessons Learned: Tools vs. Docs

Building the EKS Configurator taught me when to build tools instead of (or alongside) documentation. Here's my framework:

Build a Tool When:

✅ Configuration has many interdependencies

Manual validation is error-prone. For Weaviate on EKS, instance type affects memory, which affects storage sizing, which affects IOPS requirements, which affects volume type selection. A tool can validate these combinations automatically.

✅ Context dramatically changes recommendations

A semantic search application has different requirements than a recommendation engine. Static docs can't be sufficiently specific for every use case, but a tool can ask questions and tailor output.

✅ Syntax precision is critical

Kubernetes YAML is unforgiving. One wrong indent, one missing field, one incompatible value—and your deployment fails. Generating correct YAML prevents hours of troubleshooting.

✅ Onboarding friction is measurable

High support ticket volumes and long time-to-first-deployment indicate pain. If you're repeatedly answering the same configuration questions, that's a signal.

✅ Validation can be automated

If you can programmatically determine "this combination won't work" or "this configuration is suboptimal," build that into a tool. Don't make every user learn the hard way.

✅ You have working examples to build from

I had the Docker Configurator as a template and competitor tools as inspiration. Starting from scratch is harder.

Stick with Documentation When:

📝 The concept is fundamentally simple

Don't build a configurator for "How to install kubectl." That's over-engineering.

📝 Flexibility is paramount

Some users need complete control without guardrails. Advanced users might want configurations the tool doesn't support. Always provide an escape hatch to manual configuration.

📝 Maintenance burden would be high

If your configuration options change weekly, a tool might become a maintenance nightmare. I was lucky—EKS best practices are relatively stable.

📝 Understanding is more important than speed

Some topics require deep reading and comprehension. You can't shortcut learning Kubernetes fundamentals with a tool.

📝 The audience is already expert-level

If you're writing for platform engineers who live in Kubernetes daily, they might prefer full control over guided configuration.

The Sweet Spot: Integration

The most powerful approach isn't "tool OR documentation"—it's documentation-integrated tooling:

Tools provide fast, guided paths to success for beginners
Documentation provides depth, context, and customization knowledge for those who need it
Each links to the other contextually
Users choose their own learning path based on their experience level and timeline

I'm a technical writer who built a tool. That perspective helped me keep documentation at the center—the tool exists to make the docs more actionable, not to replace them.

Looking Forward

The EKS Configurator changed how I think about developer experience.

Short-term:

GKE and AKS configurators: Users deploy Weaviate on other Kubernetes platforms too
Terraform output: The most-requested feature from users managing infrastructure as code
Advanced customization options: More granular control for power users while keeping defaults simple

Long-term:

Interactive documentation: Embedding configurator-style tools directly in our docs site
Feedback loops: Using tool usage patterns to identify documentation gaps and unclear concepts
Multi-tool experiences: Connecting the EKS Configurator with monitoring setup tools, backup configuration tools, etc.

The bigger vision:

I want to create a full deployment journey: sizing tool → infrastructure configurator → application deployment → monitoring setup → backup configuration. Each tool focused on one problem, but all working together seamlessly.

Some think that as a technical writer, our job is to explain things clearly. But I was a developer first, and I know it's to remove friction from understanding and implementation. Sometimes that's documentation. Sometimes that's tooling. Often, it's both working together.

Key Takeaways

Some concepts are better shown through tools than explained in text - Complex, interdependent configurations benefit from interactive guidance
Tools and documentation should be tightly integrated - They're not competitors; they're complementary experiences
Interactive experiences reduce cognitive load for complex topics - Guided decision-making beats exhaustive reference material for onboarding
User feedback should drive tool and documentation evolution - Monitor both support tickets and usage patterns to identify friction
Know when to build vs. when to write - Not every topic needs a tool, but some topics desperately do

Try It Yourself

Explore the EKS Configurator and see how interactive tooling complements documentation. We'd love to hear how you're bridging docs and tools in your organization.

Questions? Feedback? Share your thoughts on building better developer experiences at the intersection of documentation and tooling.

Have you built tools to complement your documentation? What worked, what didn't, and what would you do differently? Let's continue the conversation.

Documentation Is a Decision System, Not a Knowledge Base

DanielleWashington — Sun, 04 Jan 2026 21:33:57 +0000

Think about the last time you stood in front of a restaurant menu with forty items.

You knew what each dish was. The descriptions were thorough. Everything was explained. But you still couldn't decide what to order. Too many options, not enough guidance. You wanted someone to just tell you what's good.

That's what your documentation does to users.

We've built encyclopedias when people need guides. We've cataloged every possible path when what they really need is someone to say: "Start here. This way works."

A note on context: This exploration comes from years of documenting cloud and AI-native infrastructure and developer tools, where technical decisions have real consequences. The patterns I'm sharing translate across domains, but how you apply them will depend on your specific context (regulatory requirements, user diversity, organizational politics). Take what resonates. Adapt what doesn't.

TL;DR

Documentation should help users make decisions, not just transfer knowledge.

Core ideas:

Users arrive seeking confidence to act, not information to absorb
Map the decision points in your users' journey (Day 0, Day 1, Day 2)
Provide recommendations where you can, frameworks where you can't
Decision-oriented guides complement comprehensive reference material
This approach scales beyond team constraints

Read on for the framework ↓

The Library Paradox

Imagine a library where every book exists but there's no card catalog. No librarian. No categorization system. Just millions of books and a sign that says "Everything you need is here."

Technically true. Practically useless.

This is what comprehensive documentation without decision architecture looks like. All the information exists. Users just can't find their way to the answer that matters for their specific situation at this specific moment.

The problem isn't missing information. The problem is missing navigation.

A developer opens your docs to integrate an API. The authentication section lists three methods: OAuth2, API keys, JWT tokens. Each is thoroughly explained. Security considerations are documented. Implementation complexity is clear.

The developer closes the tab.

Not because they didn't understand the options. Because they couldn't decide which option was right for them. The cognitive load of evaluation exceeded their available decision-making energy.

They went looking for a simpler product. One with opinions.

What Users Actually Come Looking For

When someone arrives at your documentation, they're usually standing at a crossroads.

"Should I use deployment pattern A or B?"
"Is this even the right tool for what I'm trying to do?"
"What breaks if I choose wrong?"

These aren't requests for information. They're requests for navigation.

Users don't want to know every possible path through the forest. They want to know: which path gets me where I'm going? What do I need to watch out for? When should I take the detour?

The difference between knowledge and wisdom. Knowledge is understanding the map. Wisdom is knowing which route to take given the weather, your skill level, and how much daylight you have left.

Most documentation stops at knowledge. The wisdom layer is missing.

💭 What crossroads do your users stand at? Where do they get stuck choosing between paths?

The Architecture of Decision

Here's how I think about mapping the decision landscape:

Day 0: Before the Journey Begins

Before users commit to your tool, they need to know if this path makes sense for them.

"Is this right for my use case?"
"What am I signing up for?"
"What does success look like on the other side?"

Think of this as the moment before you buy hiking boots. You need to know if you're going on day hikes or through-hiking the Appalachian Trail. The boots you need are different.

Day 1: The First Steps

Users have committed. Now they need to get from zero to working state without getting lost.

"Which starting configuration matches my constraints?"
"What's the fastest path to something working?"
"What decisions can I defer until later?"

This is base camp. Get the tent up. Get oriented. Don't try to summit on your first day.

Day 2: The Long Game

Now they're running in production. Different decisions matter.

"How do I troubleshoot when things go wrong?"
"When should I scale up? What's the trigger?"
"What actually matters for observability?"

This is expedition mode. You need to read the terrain, adjust to conditions, make judgment calls based on what you're seeing.

Each phase has its own decision architecture. Map these explicitly, and your documentation transforms from an information dump into a navigation system.

What Decision-Oriented Documentation Actually Looks Like

Let me show you the difference in practice.

Traditional approach (the encyclopedia):

"Our platform supports three deployment models: single-node, clustered, and distributed. Single-node deployment uses a monolithic architecture with all components running in a single process. Clustered deployment distributes components across multiple nodes with leader election. Distributed deployment uses a service mesh architecture with independent scaling of each component."

Accurate. Complete. Useless for making a decision.

Decision-oriented approach (the guide):

"Start with single-node deployment unless you need high availability. Single-node is simpler to operate and sufficient for most production workloads under 10,000 requests/minute. Move to clustered deployment when you need zero-downtime upgrades or your workload exceeds single-node capacity. Distributed deployment is for organizations running at significant scale (100,000+ requests/minute) or with complex compliance requirements. Each step up adds operational complexity. Don't optimize prematurely."

Same information at the core. Different purpose. One explains what exists. The other tells you where to start and when to change course.

Think of it like the difference between a map and turn-by-turn directions. Both are useful. But when you're driving in unfamiliar territory at night in the rain, you want directions, not a map.

The important nuance: This works when there's a legitimate "good default path." When your product serves radically different contexts (enterprise vs. startup, compliance-heavy vs. speed-focused, geographic constraints), you need decision trees, not single recommendations. The goal is reducing friction, not eliminating necessary complexity.

The Confidence Gap

Here's what I've observed watching developers interact with documentation:

They don't lack intelligence. They don't lack technical skill. What they lack is confidence that they're making the right choice given their constraints.

Confidence comes from:

Clear defaults that work for most situations
Visible tradeoffs so you understand what you're giving up
Consequence clarity so you know what happens next
Decision criteria when the answer genuinely depends on context

When users close your docs and immediately ask in Slack, "Should I use X or Y?" you haven't failed to explain. You've failed to provide navigational confidence.

They found the information. They couldn't convert it to action.

This is the gap that kills adoption. Fix it, and you've eliminated a major friction point in your user's journey.

💭 Have you watched users struggle with this in your community? What decisions trip them up?

Building Documentation That Scales Like a System

Shifting from knowledge transfer to decision architecture requires rethinking how documentation works.

Start with the Crossroads

Before writing anything, map every significant choice point in the user journey. Where do they need to make decisions? What are the implications of those decisions?

Don't guess. Don't assume. Map it based on support tickets, community questions, user research, telemetry. Find the actual friction points.

Reality check for legacy systems: You can't retrofit everything at once. Start with high-traffic pages or new features. Build the decision layer incrementally. Document the pattern, then expand it.

Know When to Guide, When to Provide Tools

Be prescriptive when:

Best practices are established in your domain
You have data on what most users choose
The "wrong" choice has manageable consequences
Your product embeds sensible defaults

Provide frameworks when:

Multiple approaches are legitimately valid
Context varies dramatically (regulatory, budget, scale)
Recommendations could create liability
The complexity is inherent, not accidental

Think of it like teaching someone to cook. For basic techniques, you give instructions: "Sear the meat at high heat for 2 minutes per side." For flavor development, you give frameworks: "Taste as you go. Add acid if it's flat, fat if it's harsh, salt if it's bland."

The goal isn't prescription for its own sake. It's reducing cognitive load where you can, and providing decision tools where you can't.

Surface What Happens Next

Users need to understand consequences before they commit to a path.

"If I choose single-node deployment, what's my migration path when I need to scale?"
"If I pick OAuth2, what's the ongoing maintenance burden?"
"If I defer this decision, what's the cost of changing later?"

Make the future visible. Let users see around corners.

Design for Contributors at Scale

When hundreds of engineers contribute to your docs, decision-oriented patterns give them scaffolding for writing better first drafts. They understand what guidance to provide, not just what features to explain.

The real talk: This still requires investment in templates, contributor guides, review processes. At a 200:1 developer-to-writer ratio, you're always triaging. Decision architecture helps, but it doesn't solve chronic understaffing. Advocate for resources where you can.

Sometimes the Fix Is the Product, Not the Docs

If users constantly struggle to choose between three authentication methods, maybe the problem isn't documentation. Maybe your SDK should pick the secure default and let advanced users override it.

Documentation can guide decisions. It can't fix bad product design. Know the difference.

The Two-Layer System

Here's what this framework does NOT mean: throw away comprehensive reference documentation.

Think of it like a building with two floors:

Ground floor: Decision-oriented guides (getting started, best practices, troubleshooting)
This is where people enter. It's optimized for navigation. Clear signage. Recommended paths. Guidance for common journeys.

Second floor: Comprehensive reference (API docs, configuration parameters, schemas)
This is where people go for precision. It's optimized for completeness. Exhaustive coverage. Neutral, factual tone. Required for complex work.

The mistake is treating the ground floor like the second floor. Or forcing the second floor to have ground floor characteristics when precision matters more than guidance.

Build the navigation layer on top of your reference foundation. Serve both purposes well.

Measuring What Actually Matters

Documentation succeeds when users can move from uncertainty to confident action with minimal friction.

The metrics that capture this:

Support tickets asking "should I use X or Y?" after reading docs
Community questions about choosing between documented options
User testing: can people confidently select a path?
Time-to-first-deployment or time-to-production
Post-implementation surveys: "Did you feel confident in your choices?"

Not whether every feature is documented. Not whether every edge case is explained. Whether users can act confidently based on what you've provided.

This requires different skills than traditional technical writing. Decision architecture. Strategic guidance. Understanding how humans actually make choices under uncertainty.

The best documentation doesn't just inform. It navigates.

Where This Works (And Where It Needs Translation)

This framework emerged from documenting developer tools and cloud infrastructure. It works particularly well for:

Product contexts:

Tools where users make architectural decisions
Platforms with multiple valid configuration paths
Services where decisions have operational consequences
Products targeting technical audiences

Organizational contexts:

Small teams relative to product surface area
Docs-as-code workflows with engineer contributions
Organizations that can iterate based on user feedback
Products with telemetry showing usage patterns

Places where you'll adapt, not adopt wholesale:

If you're documenting regulated systems (medical, financial, aerospace), compliance may require comprehensive coverage. Layer decision guides on top, but don't sacrifice required completeness.

If your product genuinely serves wildly different contexts, focus on decision criteria and multiple paths rather than single recommendations.

If you're in a highly political environment where every recommendation needs approval, start small. Prove value in one area before attempting systemic change.

The principles translate. The implementation varies.

What This Unlocks

When documentation successfully reduces decision friction, something changes.

Users adopt faster. They implement with more confidence. They require less support. Your documentation scales beyond your team's capacity to personally guide each user.

Whether you're working with a 10:1 ratio or 200:1, decision-oriented architecture lets you punch above your weight.

It's not about writing more. It's about writing strategically for the decisions that actually matter in your users' journey.

This is how documentation becomes a growth lever instead of a cost center.

Key Patterns to Remember

Map the crossroads: Identify Day 0, Day 1, Day 2 decision points
Guide where you can, provide tools where you can't: Know when to be prescriptive vs. when to offer frameworks
Make consequences visible: Help users see around corners
Layer navigation over reference: Serve both purposes, optimized differently
Measure decision confidence: Track whether users can act, not just whether content exists
Adapt to your context: These principles translate, but implementation varies by domain

An Invitation to Explore

Try this experiment this week:

Pick one feature in your docs
Map every decision a user must make to use it successfully
Ask: does your documentation explicitly guide each decision?

Share what you discover 👇 I'm particularly interested in hearing from folks in different domains (enterprise software, regulated industries, legacy systems). How do these patterns need to adapt for your context?

Users don't come to documentation seeking knowledge. They come seeking confidence to act. The question is: are you providing it?

From Code to Clarity: Embedding Technical Writers in Engineering Teams

DanielleWashington — Tue, 09 Jul 2024 01:24:24 +0000

Engineering teams are the face of technological innovation, they focus on developing new products, improving existing systems, and solving complex technical challenges. But their success often hinges on clear and effective communication, both within the team and with external stakeholders. This is where technical writers play a crucial role.
When the expertise of technical writers, and technical content teams, is leveraged, documentation quality is enhanced, communication is streamlined, and ultimately project outcomes are improved. You can think of technical writers as the engineering team’s secret weapon. Let’s explore how engineering teams can effectively utilize their technical communication teams to their advantage.

The Role of Technical Writers in Engineering

Technical writers specialize in crafting clear, concise, and accurate documentation that translates complex technical information into accessible content. Our work encompasses a wide range of documents, including, but not limited to:

Onboarding guides
User manuals
Release notes
Runbooks
Technical guides
API documentation
Training materials
System documentation
Process and procedure documentation

By producing high-quality documentation, technical writers help ensure that all stakeholders—developers, end-users, and business partners—understand the technical aspects of a project or software. This clarity is vital for the successful implementation and adoption of engineering solutions.

Benefits of Integrating Technical Writers into Engineering Teams

Enhanced Documentation Quality

Engineering projects often involve intricate systems and complex procedures, and we bring a unique skill set that includes the ability to understand technical details and translate them into user-friendly content. We specialize in demystifying confusing technical terms without confusing jargon while also adhering to specific style guides. Have you ever had an engineer attempt to explain a complex, technical feature?

Improved Communication

Clear documentation facilitates better communication within the engineering team and with external parties. As technical writers, we act as intermediaries who can convey technical information in a manner that is understandable to non-technical stakeholders. This can prevent misunderstandings and ensure that everyone has a clear understanding of the work completed. For example, release notes can be confusing to the uninitiated with terms and phrases that aren’t quite understandable. A technical writer working on release notes can craft release notes that accurately describe any new changes and features of a product, and ensure that the release notes are “executive-ready.”

Increased Efficiency

With technical writers handling the documentation, engineers can focus more on their core tasks—designing, developing, and testing. This division of labor ensures that engineers are not bogged down by writing tasks and can contribute more effectively to the project’s technical aspects.

Consistency Across Documentation

Technical writers ensure that all project documentation adheres to a consistent style and format. This consistency is crucial for maintaining a professional standard and ensuring that documents are easy to navigate and use. It also helps in creating a cohesive brand image and enhances the user experience. Imagine Engineer A writing a document in Confluence while Engineer B creates the same document using GitHub/Markdown. Having a technical documentation team ensures that these occurrences are far and few in between.

Fostering collaboration with the technical writers on your team

Early Involvement

From the onset of a project, technical writers need to be involved. It may seem trivial to have writers attend kick-off meetings and planning meetings, but it is imperative that the documentation team is able to attend. This allows for the team to gain a comprehensive understanding of project goals, technical requirements, key milestones, and any existing pain points that can be resolved with a simple runbook or addition to existing documentation. Early involvement ensures that all documentation is developed concurrently, rather than as an afterthought.

Regular Communication

Maintaining regular communication between technical writers and engineers is essential. This can be facilitated through regular meetings, collaborative tools, and shared documentation platforms. Regular updates help technical writers stay informed about project developments and allow them to ask questions and clarify technical details as needed. Again, ensuring that writers are included in weekly status meetings can ensure that pain points are quickly addressed.

Access to Subject Matter Experts

Technical writers need direct access to subject matter experts (SMEs) within the engineering team, in fact when a user story is created for a piece of documentation, a SME should be mentioned. SMEs can provide detailed explanations and answer specific questions that help technical writers create accurate and detailed documentation. This collaboration ensures that the documentation is technically sound and comprehensive.

In conclusion, technical writers are invaluable assets to engineering teams, providing expertise in creating clear, concise, and accurate documentation. By integrating technical writers into their teams, engineers can enhance documentation quality, improve communication, and increase overall project efficiency. Implementing best practices for collaboration ensures that technical writers can effectively contribute to the success of engineering projects, ultimately leading to better outcomes and more satisfied stakeholders.