17 Concepts for Transitioning to Developer Documentation  🔗 **Source:** [17 Concepts for Transitioning to Developer Documentation]() ## Highlights - First-party developers are the engineers inside your organization. They built the thing. ([Location 48](https://readwise.io/to_kindle?action=open&asin=B0GX34M77Z&location=48)) - Tags: aqua - Second-party developers are partners and enterprise integrators. ([Location 51](https://readwise.io/to_kindle?action=open&asin=B0GX34M77Z&location=51)) - Tags: aqua - Third-party developers are the public — and they are the most demanding audience of all. ([Location 55](https://readwise.io/to_kindle?action=open&asin=B0GX34M77Z&location=55)) - Tags: aqua - Tutorials are for learning. ([Location 81](https://readwise.io/to_kindle?action=open&asin=B0GX34M77Z&location=81)) - Tags: aqua - How-to guides are for doing. ([Location 85](https://readwise.io/to_kindle?action=open&asin=B0GX34M77Z&location=85)) - Tags: aqua - Reference documentation is for looking things up. ([Location 88](https://readwise.io/to_kindle?action=open&asin=B0GX34M77Z&location=88)) - Tags: aqua - Explanations are for understanding. ([Location 92](https://readwise.io/to_kindle?action=open&asin=B0GX34M77Z&location=92)) - Tags: aqua - The discipline of Diátaxis is not in learning the four types. It is in keeping them separate. ([Location 96](https://readwise.io/to_kindle?action=open&asin=B0GX34M77Z&location=96)) - Tags: aqua - The insidious thing about the curse of knowledge is that it gets worse as you get better. ([Location 109](https://readwise.io/to_kindle?action=open&asin=B0GX34M77Z&location=109)) - Tags: aqua - maintain one source of truth for conceptual documentation — what a feature does — and three separate surfaces for how to use it. Do not repeat the concept three times. Do repeat the examples, ([Location 154](https://readwise.io/to_kindle?action=open&asin=B0GX34M77Z&location=154)) - Tags: aqua - One minute: the first successful call. Its purpose is not to teach anything. It is to make the system feel real and achievable. ([Location 176](https://readwise.io/to_kindle?action=open&asin=B0GX34M77Z&location=176)) - Tags: aqua - Ten minutes: a working prototype. The developer has moved past hello world and is now doing something resembling their actual use case. ([Location 180](https://readwise.io/to_kindle?action=open&asin=B0GX34M77Z&location=180)) - Tags: aqua - One hundred minutes: production-ready. Rate limiting understood, error handling implemented, retry logic in place, security considerations addressed. This is the documentation that enterprise developers need before they commit to an integration. ([Location 183](https://readwise.io/to_kindle?action=open&asin=B0GX34M77Z&location=183)) - Tags: aqua - Pull documentation is what developers seek. Reference pages, troubleshooting guides, error code explanations. ([Location 202](https://readwise.io/to_kindle?action=open&asin=B0GX34M77Z&location=202)) - Tags: aqua - Push documentation is what you deliver proactively. Changelogs, deprecation notices, release notes, migration guides. ([Location 206](https://readwise.io/to_kindle?action=open&asin=B0GX34M77Z&location=206)) - Tags: aqua - This is the concept called dogfooding: using your own product exactly the way your users use it. ([Location 256](https://readwise.io/to_kindle?action=open&asin=B0GX34M77Z&location=256)) - Tags: aqua - the versioning strategy you adopt directly determines whether your documentation can stay current. ([Location 325](https://readwise.io/to_kindle?action=open&asin=B0GX34M77Z&location=325)) - Tags: aqua - Beta is a promise that things may change. ([Location 336](https://readwise.io/to_kindle?action=open&asin=B0GX34M77Z&location=336)) - Tags: aqua - General availability is a commitment. GA documentation is what enterprise customers rely on in production systems. ([Location 339](https://readwise.io/to_kindle?action=open&asin=B0GX34M77Z&location=339)) - Tags: aqua - The deprecation notice had to answer three questions precisely: what is being deprecated, when will it stop working, and what is the migration path. But it also had to be present at the point of use — on the reference page for the deprecated field, not only in a separate migration guide. ([Location 344](https://readwise.io/to_kindle?action=open&asin=B0GX34M77Z&location=344)) - Tags: aqua - A changelog is a record. A migration guide is an instruction set. ([Location 356](https://readwise.io/to_kindle?action=open&asin=B0GX34M77Z&location=356)) - Tags: aqua - Progressive disclosure is the principle that information should be presented in layers, with the most essential information first and the most complex information available but not mandatory. ([Location 401](https://readwise.io/to_kindle?action=open&asin=B0GX34M77Z&location=401)) - Tags: aqua - the faster a developer can experience success, the more likely they are to continue. ([Location 436](https://readwise.io/to_kindle?action=open&asin=B0GX34M77Z&location=436)) - Tags: aqua - Documentation is written at a distance from the developer who will use it — temporally, contextually, and cognitively. The writer knows the product. The developer knows their task. These two kinds of knowledge are not the same, and the gap between them produces documentation that is accurate but fails. Feedback loops are the mechanism by which the developer’s knowledge reaches the writer. ([Location 469](https://readwise.io/to_kindle?action=open&asin=B0GX34M77Z&location=469)) - Tags: aqua