Technical Documentation
Rainkit's "Getting Started" page has grown to 4,000 words. It walks a beginner through a first call, lists every parameter of every endpoint, explains how to cache forecasts, and ends with an essay on forecast accuracy. Beginners get lost halfway down. Experienced developers can't find the one fact they need. The page tries to serve everyone and serves no one.
The rule
Each page serves one need: learn, do, look up, or understand.
Readers arrive at documentation with one of four needs, and each need calls for a different kind of page. A widely used model called Diátaxis names them like this:
| Page type | The reader is thinking | Rainkit example |
|---|---|---|
| Tutorial | "Teach me." | Build your first rain alert |
| How-to guide | "Help me do this one thing." | Cache forecasts to stay under your daily limit |
| Reference | "What exactly is X?" | GET /v1/forecast: parameters and responses |
| Explanation | "Why does it work this way?" | How Rainkit turns radar and satellite data into a probability |
Each type is written differently:
- A tutorial holds the learner's hand along one safe path that always ends in success. It avoids choices and side-trips, because a beginner cannot judge them yet.
- A how-to guide assumes the basics and goes straight to the steps for one task.
- Reference is complete, consistent and plain. Every endpoint is described in the same order, so readers can scan it.
- An explanation gives background, reasons and trade-offs. It is the one place where discussion belongs.
Treat the docs as part of the product. They need owners, reviews and updates whenever the product changes, and pages should link to each other so a reader can move from one need to the next.
The shortcut
For every page, and every paragraph on it, ask: "What is the reader thinking as they arrive?" When a paragraph answers a different need than its page, move it to the right page and leave a link behind.
Tutorial
Keep only sign-up, getting a key, the first call and printing the result: one clear path to success.
The trap is the everything page: it teaches, lists and explains at once, and does none of them well. Length is not the problem; mixing needs is.
Drills
Answer fast — trust the rule.
A developer who has used Rainkit for months wants the exact allowed range of the hours parameter. Which page type do they need?
"How to retry safely when you hit the daily limit" is which type of page?
Why shouldn't a tutorial offer the learner many options at each step?
While editing a how-to guide, Meera finds three paragraphs on how radar works. What should she do?
Remember
- Each page serves one need: learn, do, look up, or understand.
- Shortcut: ask what the reader is thinking as they arrive, and move stray paragraphs to the right page.
- Trap: the everything page, which teaches, lists and explains at once.