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:
| Document | Audience | Length | Format |
|---|---|---|---|
| Technical Specification | Developers | 75 pages | Detailed, code-heavy |
| Operations Runbook | Operations Staff | 12 pages | Step-by-step, screenshots |
| Business Guide | Business Analysts | 8 pages | Plain English, checklists |
| Compliance Evidence | Compliance/Security | 5 pages | Policy 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