// journal
Notes on writing docs people can follow.
Short, practical essays from our writers.
- 1 min
Why most technical docs fail, and how to fix them
It's rarely that the writer misunderstands the product. It's that the docs were written for the writer, not the reader.
StrategyWriting - 1 min
Docs are a product: how to measure them
If you can't say whether your documentation is working, you can't improve it. Five metrics that tell you.
StrategyMetrics - 1 min
OpenAPI is a contract, not documentation
A spec that only exists to generate a reference page will drift. Treat it as the contract and everything gets easier.
APIOpenAPI - 1 min
Ship docs with the feature: a definition of done
The cheapest time to write documentation is while the feature is fresh. Build that into how work is finished.
ProcessDocs-as-code - 1 min
Building a docs site that scores 100 on Lighthouse
Documentation is the perfect static workload. Here's how to keep it fast, accessible and easy to search.
Web developmentPerformance