The earlier archive Written for a different audience — operations teams, business stakeholders, new joiners. It is kept unchanged, with its original date, because a dated body of work says something a rewritten one cannot.

Technical Documentation That Business Teams Actually Use

It was April 2023 at Exclusive IT Solutions. We had just completed a major integration project with a logistics company.


The Documentation Nobody Read

It was April 2023 at Exclusive IT Solutions. We had just completed a major integration project with a logistics company.

We were proud of our documentation:

  • 75-page technical specification
  • Complete API reference
  • Detailed data mapping documentation
  • Security and compliance guides

It was comprehensive. It was accurate. It was professional.

Six weeks after handoff, their IT director called me.

"Our team can't use this documentation," he said. "It's... too technical."

"What do you mean?" I asked. "Everything's documented."

"Yes," he said. "But we have operations staff who need to monitor this integration. And business analysts who need to troubleshoot. And your documentation is... written for developers."

I was defensive initially. "It's technical documentation. Of course it's written for developers."

"Right," he said. "But the people who need to use it aren't developers."

We had written comprehensive documentation for the wrong audience.

The Metaphor: The Owner's Manual vs. The Driver's Guide

Let me explain with a metaphor that transformed my documentation philosophy.

Imagine you buy a new car. You get two documents:

Document 1: The Owner's Manual

  • 200 pages
  • Every technical specification
  • Every component explained
  • Every wiring diagram included

It tells you exactly how the car works. How the engine is assembled. How the transmission operates. What every sensor does.

Document 2: The Driver's Guide

  • 20 pages
  • How to start the car
  • What each dashboard light means
  • How to change the oil
  • What to do if it won't start
  • Basic troubleshooting

It tells you how to use the car. What's normal. What's a problem. How to fix simple issues.

Who reads what?

Drivers read the driver's guide. They need to know how to use the car.

Mechanics read the owner's manual. They need to know how the car works.

We were writing owner's manuals for drivers.

The Struggle: The "One-Size-Fits-All" Documentation Mindset

I'll be honest: we had a documentation template. We followed it for every project.

The template was perfect for technical specifications. It was perfect for developers.

We just assumed that was "documentation."

We never asked: Who's going to use this? What do they need to know?

The Transformation: Audience-Centric Documentation

That call changed everything. We developed a framework for creating documentation that different audiences actually use.

The "Audience-First" Documentation Framework

Principle 1: Identify Your Audiences Before You Write

Before you write anything, ask:

  • Who will use this documentation?
  • What are they trying to do?
  • What's their technical comfort level?

Example - Logistics Integration:

Audience 1: Developers (Technical comfort: High)

  • What they need: API specifications, data structures, integration patterns
  • Format: Code samples, detailed technical specs, error codes

Audience 2: Operations Staff (Technical comfort: Medium)

  • What they need: How to monitor the system, what errors mean, who to contact for help
  • Format: Screenshots, step-by-step guides, error code translations

Audience 3: Business Analysts (Technical comfort: Low)

  • What they need: How to verify data is flowing, how to troubleshoot issues, what reports to run
  • Format: Plain English, business metrics, checklists

Audience 4: Compliance/Security (Technical comfort: Varies)

  • What they need: Evidence data is secure, audit trails, compliance verification
  • Format: Policy references, audit checklists, compliance mappings

Principle 2: Separate Documents for Different Audiences

Don't create one document for everyone. Create specific documents for each audience.

What we created:

DocumentAudienceLengthFormat
Technical SpecificationDevelopers75 pagesDetailed, code-heavy
Operations RunbookOperations Staff12 pagesStep-by-step, screenshots
Business GuideBusiness Analysts8 pagesPlain English, checklists
Compliance EvidenceCompliance/Security5 pagesPolicy references, checklists

Principle 3: Each Document Answers Different Questions

Technical specification answers: "How does this work?" Operations runbook answers: "How do I use/monitor/troubleshoot this?" Business guide answers: "How do I know this is working? What do I do if it's not?" Compliance evidence answers: "Are we compliant? What's the proof?"

Principle 4: Format for the Audience, Not for You

Developers like: Code samples, technical diagrams, detailed specs Operations staff like: Screenshots, step-by-step guides, error translations Business people like: Plain English, business metrics, checklists Compliance people like: Policy references, audit trails, evidence summaries

The Real-World Example: The Logistics Integration

Let me show you what changed when we applied this framework.

Before: The 75-Page "Everything" Document

One massive document that tried to cover everything.

What was in it:

  • Complete technical specifications
  • API reference
  • Data mapping documentation
  • Security and compliance information
  • Deployment instructions
  • Troubleshooting guide

What was wrong:

  • Developers had to sift through 75 pages to find technical details
  • Operations staff got lost in technical details they didn't understand
  • Business analysts couldn't find the business metrics they needed
  • Compliance officers had to extract evidence from technical documentation

Result: Nobody read it. Everyone called the development team for help.

After: The Four-Audience Approach

We replaced one 75-page document with four targeted documents.

Document 1: Technical Specification (75 pages, developers only)

What's in it:

  • Complete API specification with code samples
  • Data structures and mappings
  • Security implementation details
  • Error codes and handling patterns
  • Integration patterns and best practices

Who uses it: Developers

Document 2: Operations Runbook (12 pages, operations staff)

What's in it:

  • How to start and stop the system (5 steps)
  • What each monitoring metric means (with screenshots)
  • Common errors and what to do (error code → plain language translation)
  • Who to contact for each type of problem
  • Daily/weekly/health check procedures

Example from runbook:

ERROR: API_TIMEOUT
What it means: The connection between systems is too slow

What to check:
1. Is your internet working? (Try opening a website)
2. Is the partner system online? (Check status page)
3. Has this happened before? (Check recent incidents)

What to do:
- Wait 2 minutes and try again
- If it keeps happening, call: IT Support (ext. 501)
- If it's urgent, call: On-call manager (ext. 555)

Who uses it: Operations staff

Document 3: Business Guide (8 pages, business analysts)

What's in it:

  • What the system does (in 1 page, plain English)
  • How to know it's working (5 metrics to check daily)
  • What's normal behavior (what to expect)
  • What's a problem (what to watch for)
  • Simple troubleshooting (3-step process)
  • Who to contact for each type of issue

Business metrics to check daily:

DAILY HEALTH CHECK (takes 5 minutes)
☐ 1. Are orders being exchanged? (Check dashboard)
☐ 2. Is the error rate below 1%? (Check dashboard)
☐ 3. Are recent orders showing in reports? (Check report)
☐ 4. Have there been any alerts in the last 24 hours? (Check inbox)

If all yes → System is healthy ✓
If any no → Call IT Support (ext. 501)

Who uses it: Business analysts

Document 4: Compliance Evidence (5 pages, compliance/security)

What's in it:

  • What regulations this system complies with (GDPR, industry-specific)
  • How data is protected (encryption, access controls)
  • Audit trail evidence (what's logged, how to retrieve)
  • Compliance checklist for auditors
  • Mapping from technical controls to compliance requirements

Compliance checklist:

GDPR COMPLIANCE CHECKLIST
☐ Data is encrypted in transit (HTTPS/TLS) ✓
☐ Data is encrypted at rest (database encryption) ✓
☐ Access controls are enforced (role-based permissions) ✓
☐ Audit logs are retained for 7 years ✓
☐ Data deletion requests are processed within 30 days ✓
☐ Data breach response plan is documented ✓

Evidence references:
- Encryption: Technical spec, section 4.2
- Access controls: Technical spec, section 5.1
- Audit logs: Technical spec, section 6.3
- Deletion process: Business guide, section 3.2
- Response plan: Operations runbook, section 7

Who uses it: Compliance and security teams

The Results: Measurable Impact

Documentation Usage

Before: 12% of stakeholders accessed the documentation After: 87% of stakeholders accessed relevant documentation Increase: 625% more usage

Support Requests from Client

Before: 45 support requests per month (mostly "how do I...") After: 12 support requests per month (mostly genuine issues) Reduction: 73% fewer requests

Time to Find Answers

Before: Average 15 minutes to find information in the 75-page document After: Average 3 minutes to find information in targeted documents Improvement: 80% faster

Stakeholder Satisfaction

Before: 2.4/5 for documentation After: 4.7/5 for documentation Increase: 96% higher satisfaction

Developer Time Saved

Before: Developers spent 8 hours per month answering documentation questions After: Developers spent 1 hour per month answering documentation questions Saving: 87.5% less time on documentation support

The Metaphor: The Library vs. The Bookstore

I like to explain this with another metaphor:

One-document-for-everyone is like a library that organizes all books by size.

You want a cookbook. You go to the cooking section. But books are organized by thickness, not type. The 200-page philosophy book is next to the 50-page cookbook. You can't find what you need.

Audience-specific documentation is like a bookstore organized by category.

Cookbooks are in the cooking section. Technical manuals are in the reference section. Fiction is in the literature section.

You walk to the right section. You find exactly what you need in minutes.

Good documentation is organized by who needs it, not by how comprehensive it is.

Common Mistakes to Avoid

Mistake 1: One Document for Everyone

The Problem: "Let's create comprehensive documentation covering everything"

The Fix: Identify your audiences. Create separate documents for each.

Mistake 2: Writing in Technical Language for Non-Technical Audiences

The Problem: "The system implements OAuth 2.0 with token refresh mechanisms"

The Fix: "The system uses secure login that automatically keeps you logged in"

Mistake 3: Assuming Technical Level Instead of Asking

The Problem: "Developers need this much detail, so everyone does"

The Fix: Ask each audience what they need. Don't assume.

Mistake 4: Including Irrelevant Information for the Audience

The Problem: Technical spec includes deployment instructions (developers don't need this)

The Fix: Each document focuses on what that audience needs.

Mistake 5: Not Testing Whether People Can Actually Use It

The Problem: We wrote it, we published it, we're done

The Fix: Give draft documentation to representatives of each audience. Watch them try to use it. Fix what doesn't work.

The Hard Truth

Comprehensive documentation that nobody reads is worse than no documentation.

With no documentation, people ask questions. You answer them. You learn what they need.

With comprehensive documentation nobody reads, you think it's done. You stop learning. People struggle silently until they can't anymore, then they call—frustrated that the documentation didn't help.

Good documentation is documentation that people actually use.

A Framework for Your Documentation

If you're creating documentation:

Step 1: Identify Your Audiences

Who will use this? What do they need to know?

Step 2: Create Separate Documents

One document per audience. Not one document for everyone.

Step 3: Answer Different Questions

Technical: How does it work? Operations: How do I use/troubleshoot it? Business: How do I know it's working? What do I do if it's not? Compliance: Are we compliant? What's the proof?

Step 4: Format for the Audience

Developers get code. Operations staff get screenshots. Business people get plain language. Compliance people get checklists.

Step 5: Test with Real Users

Don't publish until representatives of each audience can actually use it.


Quick Documentation Planning Template

DOCUMENTATION PLANNING
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

PROJECT: _______________________

AUDIENCE IDENTIFICATION
Who will use this documentation?
[ ] Developers
[ ] Operations Staff
[ ] Business Users/Analysts
[ ] Compliance/Security
[ ] Other: _____________________

FOR EACH AUDIENCE:

AUDIENCE: _______________________
Technical Comfort: [ ] High [ ] Medium [ ] Low

What do they need to do?
_____________________________________________

What questions do they need answered?
_____________________________________________

DOCUMENTATION PLAN
Document Title: _______________________
Length: _____ pages
Format: [ ] Technical spec [ ] Runbook [ ] Guide [ ] Evidence [ ] Other: _____

Content Outline:
1. _______________________
2. _______________________
3. _______________________

When will we test this with real users?
Date: _______________________

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

What's your documentation strategy? Do people actually use it?

#Documentation #KnowledgeManagement #TechnicalWriting #Communication #AudienceCentric

The archive

Every article, 2013–2026

Thirty dated articles on application support, delivery, infrastructure and data — plus the recent writing on CI/CD reproducibility and offline-first design.

The recent work is written for a specialist audience, and it is where the measurement discipline is set out in full.

Recent writingOpen Source Impact