Everyone Is Busy! A Docs Strategy
When should you add visual elements to your docs? Let’s get back to the heart of what docs really are: solving problems when someone failed to complete a task with just vibes.
There’s a big divide between gen pop docs and developer docs. Everyone wants to hear hot takes about how to market to developers - how they’re so lazy and so smart and please don’t insult their intelligence. I’m an engineer and I’m here to tell you that I don’t think engineers are super efficient or super smart, they’re just busy. Everyone is busy!
Good docs respect people’s time. Take pointers from software development principles - if your code is getting too complex, modularize it. Break it up into smaller pieces until it is easier to digest. Visuals are one of the most effective ways to do this; they can replace walls of text, isolate complex concepts, or provide quick reference points.
AI isn’t a magic fix that removes the need for clarity. If anything, it raises the stakes because now you have two potential points of failure: bad docs confusing humans directly and bad docs causing AI to give inaccurate answers to humans.
In This Post
The Problem
Everyone is busy, context-switching constantly, and just trying to solve their immediate problem, not deeply understand the system - that might happen later, or over time through solving immediate problems over and over. I’m not saying that it’s ideal, but it happens.
This echoes my experiences in food and fine arts archiving. Chefs always wanted to wax poetically about their precious recipes when everything is literally on fire - cool story bro, just give me the goods: ingredients, measurements, steps.
While helping people navigate complex information systems in special collections archives, I learned that people don’t respond well to prescribed paths, they want to choose their own adventure.
Forcing everyone into the same linear path of dense text creates a traffic jam. Good docs are a well-designed highway system with clear exits, multiple routes, and signs that tell you exactly which lane to take.
People often only consult docs when they have a problem. So solve their problem! Use visuals to keep it scannable, actionable, and readable, because most people would rather enjoy the thing than get stuck in the docs about the thing.
but might break later Note over Dev,Docs: Problem "solved"
but tech debt created
The AI Amplifier
It’s not just busy humans reading your docs, it’s busy humans using AI to read your docs for them. AI tools are scanning your docs the same way any tired human would - looking for the answer, not the journey, except AI does it in milliseconds across your entire docs site, meaning -
-
Structure Matters: AI surfaces what’s clear, buries what’s vague
AI rewards structure over prose. If your answer is buried in walls of text, it’s more likely to get missed or misinterpreted. If it’s frontloaded with clear structure, AI quotes it directly and accurately.
-
Format Matters: AI rewards meaningful, dynamic docs
Descriptive headers complementing actionable visuals - code blocks, diagrams, screenshots, and tables - streamline AI parsing and extraction. Dense paragraphs force AI to guess what’s important.
-
Impact Matters: AI democratizes unhelpful docs
Only patient readers would suffer through 800-word timestamp essays before. Now AI summarizes it poorly for everyone, spreading confusion far and wide - faster.
ISO 8601 format with example AI-->>Dev: Accurate, actionable response Note over Dev: Problem solved ✓ else Bad Docs Docs-->>AI: Answer buried in prose AI-->>Dev: Vague and/or hallucinated response Note over Dev: Tries wrong format,
creates tech debt end Note over Dev,Docs: Structure determines accuracy
The Strategy
Visual, Scannable, Actionable, Readable
How do you design docs that respect people’s time, offer multiple entry points, and stay effective in an AI-mediated world? Here’s a framework that’s ordered by what matters most when people come to the docs with a problem to solve:
-
Visual = Assume Long Text Blocks Are Invisible
When docs get long, people’s eyes glaze over. That text block might as well not be there. LLMs have the same problem and will extract information more accurately from structured formats than from prose. Whether someone’s reading directly or asking AI to summarize, dense text is a liability.
I learned this the hard way when I wrote a procedural guide for a database migration - 12 steps in careful prose. No one read it. People kept making the same mistakes and asking questions in Slack that were outlined in the doc. When I rewrote it as an annotated flowchart, suddenly people could follow it.
Prose can be a blocker to people in problem-solving mode. As discussed in Anti-pattern: Magic Numbers - Cognitive Load Theory aka “your brain’s tab limit”: one can only consider a certain amount of details at a time. If you “have too many tabs open” - you’ll have a harder time solving your problem and prose can be a tab multiplier.
Note: This explanation framework uses prose and links (literally more tabs) because it’s conceptual, intending to teach why this strategy works - but good docs for problem-solving should default to visual and scannable.
Not everyone’s tabs are arranged in the same way either. People want to wander and not be lectured at. Visual docs create multiple access points and paths. A diagram can help someone jump to the piece they need. An annotated screenshot shows them exactly where to look. A table lets them compare options at a glance.
Scenario Visual Solution Why It Works 5+ sequential steps Flowchart Shows the path and decision points at a glance Comparing 3+ options Table Side-by-side comparison beats reading paragraphs Explaining UI interactions Annotated Screenshot “Click here” > “Navigate to the settings panel in the upper right” System Architecture Diagram Shows relationships and data flow visually Complex Conditional Logic Decision Tree Maps all the if/then branches people need to navigate Code Snippets Inline Comments Explains what’s happening without breaking flow In Practice:
Think like a chef reviewing a recipe. You don’t need to be sold the recipe, you’re already using it. You don’t need a story about how this dish represents the author’s childhood in Provence. Visually scannable ingredients, measurements, and steps - that’s what engineers want too.
-
Scannable = Assume Nobody Reads Top-to-Bottom
Docs need to work for someone who’s skimming, searching, jumping halfway through, or learning how to use AI effectively. People need to be able to access information from wherever they land, and that’s almost never from page one.
Technique Why It Matters Example Descriptive Headings That Answer Questions People scan headers to find their section Not “Overview” but “When to use the bulk processing API vs. individual transactions” Frontload the Answer Put solution first, explanation second “Use ISO 8601 format (YYYY-MM-DDTHH:mm:ssZ). This ensures consistent timezone handling across services.” Visual Hierarchy Create scannable “checkpoints” Use formatting breaks so someone can land on the section they need <!-- Top-heavy prose challenges humans and AI --> ## Timestamp Handling Our API uses timestamps in several places. It's important to understand how timestamps work because they affect caching, rate limiting, and data consistency. When you send a request... --- <!-- Actionable --> ## Use ISO 8601 format for all timestamps **Format:** `YYYY-MM-DDTHH:mm:ssZ` **Example:** `2026-02-05T14:30:00Z` Why this matters: Ensures timezone consistency across services and prevents caching issues. [See: Timestamp handling in rate limiting →]In Practice:
Special collections researchers usually don’t start at Box 1, Folder 1. They scan the finding aid, land somewhere interesting, and explore from there. Your docs should work the same way. Regularly test whether an LLM can extract the correct answer from your docs without hallucinating.
-
Actionable = Assume Everyone Has a Specific Problem
People who wake up thinking, “I’d love to learn about your payment processing architecture today” is probably a very short list. Most people come to your docs because they have a very specific problem: their integration isn’t working, they need to implement a feature, something broke and they need to fix it. Help them fix it.
Technique Why It Matters Example - Human and AI Readers Start with the task, not the explanation People have a specific problem to solve “To process a refund:” not “Understanding refund processing:” Code Samples Over Prose Show don’t tell when possible Working code example beats paragraph explanation; AI extracts and modifies working code samples, but can’t fix broken concepts Copy-paste-friendly Examples Let people get started immediately Real values, not <YOUR_VALUE_HERE>Expected Outcomes Tell people what success looks like Show the response they should see when it works; AI uses these to validate its suggestions to users <!-- Top-heavy Prose --> ## Refund Processing Refunds are handled through the refund endpoint. You'll need to provide the original transaction ID and the amount to refund. Note that partial refunds are supported.# Copy-paste-friendly Examples # Process a refund curl -X POST https://api.example.com/v1/refunds \ -H "Authorization: Bearer sk_live_abc123" \ -d transaction_id="txn_xyz789" \ -d amount=2500 \ -d reason="customer_request" # Success Response - JSON { "id": "ref_def456", "status": "completed", "amount": 2500, "transaction_id": "txn_xyz789" } # Options for more info **Next steps:** - Check refund status: `GET /v1/refunds/{refund_id}` - For partial refunds, set `amount` to less than the original transaction - See: Refund webhooksIn Practice:
Back to the kitchen. When you’re in the weeds during service and need to know “how long does this go in the oven?” you don’t want a lecture on heat transfer. You want “425°F, 12 minutes.” That’s actionable.
-
Readable = Everyone’s Busy and Tired
Cognitive load is real. Whether or not someone is using AI to read your docs at 2 AM during an incident, they’re likely not operating at full capacity. Someone reading on their phone while commuting is not either. Aim to make the docs readable for both humans and AI:
Technique Why It Matters Example Short sentences. Short paragraphs. Lots of whitespace. Reduce cognitive load Break up dense text so people can breathe One concept per chunk Avoid overwhelming readers If you’re explaining three things, use three distinct sections with clear headers Progressive Disclosure Respect different depth needs Give the essential info first, link to deeper explanations for people who want them Conversational Tone Make it approachable You’re helping a colleague, not writing a textbook In Practice:
Rarely do readers come to your docs prepared to absorb a novel. They’re context-switching, they’re multi-tasking, and probably not a prompt engineer. Whether they’re reading directly or asking an LLM for help - make it easy.
The Framework in Practice
| Step | Action | Goal |
|---|---|---|
| Ask | Identify the core question | What is the reader trying to do or figure out? |
| Answer | Answer it immediately | Put the solution in the first 2-3 lines |
| Explain | Provide the minimal viable explanation | Just enough context to use it correctly |
| Structure | Make it scannable | Headers, formatting, visual breaks |
| Visualize | Add visuals if it’s getting long | Diagram, screenshot, table, code sample |
| Expand | Link to deeper content | For people who want/need more |
Usability Test: Can a new reader skim it and solve their problem in under 2 minutes? If not, iterate.
The Payoff
Good docs aren’t always about being comprehensive. It’s about being useful to someone’s who’s busy, distracted, trying to solve a specific problem, and learning how to use AI to do it:
| Outcome | Impact |
|---|---|
| Reduced Time-to-Resolution for Common Issues | Engineers find answers in runbooks faster |
| Fewer “How do I…?” questions in Slack | People self-serve |
| AI Accuracy | When readers ask “How do I …” AI returns helpful responses instead of hallucinations |
| Higher Docs Usage Metrics | People actually reading what you wrote |
| Better Onboarding Experience | New engineers ramp up independently |
Summary
-
Everyone is Busy!
Respect people’s time with clarity. Structure your docs like modular code - break it up into smaller pieces until it’s easier to digest.
-
People Often Only Consult Docs When They Have a Problem
So solve their problem! Frontload the solution, give them the option to explore more context if they so choose.
-
Create Multiple Entry Points
Readers should be able to jump in anywhere and find what they need. Visuals and scannable structure let people navigate on their terms.
-
Visual > Text When Things Get Long
When do you add visual elements? When docs gets long. Diagrams, screenshots, tables, flowcharts - these aren’t decoration, they’re navigation tools and comprehension aids.
-
Everyone Would Rather Enjoy the Thing Than Get Stuck in the Docs About the Thing
Keep it scannable, actionable, and readable. Like a good recipe: ingredients, measurements, steps. No stories about Provence.
-
Write for AI-Mediated Consumption
Whether someone reads your docs directly or asks an AI to summarize them, the same principles apply: clear structure, frontloaded answers, and scannable format. Good docs aren’t just AI-friendly, they’re AI-proof against bad prompts. Even if someone asks AI a vague question, good docs mean AI can still extract the right answer.