Posts tagged "Documentation"

If Your API Needs a 40-Page Docs Site, Your API Is Bad

I should not need to read a novel to call your endpoint. If your API documentation spans forty pages, multiple guides, a getting started tutorial, a concepts section, a best practices section, and a troubleshooting FAQ, your API is not well documented. Your API is badly designed. The documentation is compensating for failures that should have been fixed in the API itself. Good APIs are self-evident. You look at the endpoint, you understand what it does. You look at the request, you understand what to send. You look at the response, you understand what you got back. The documentation exists to confirm what you already intuited, not to explain an incomprehensible system.

Nobody Tells You How Hard It Is to Write Technical Documentation

I have spent more time than I care to admit writing technical documentation for Aurelia 2. The docs at docs.aurelia.io have been through countless revisions, rewrites, restructures, and moments where I stared at the screen wondering if I had forgotten how to form sentences. Writing code is hard. Writing about code in a way that helps other people write code is harder. Nobody prepares you for this. The first thing you learn is that you do not actually understand the thing you are documenting. You think you do. You have used it, you have built things with it, you can explain it to a colleague at your desk.