The most important part of technical writing

The main purpose of API documentation writing is to save time and reduce frustration for the reader.

The next few posts will be about the writing part of API docs, and the principle in the first sentence is the best place to start, because almost everything else that you need to know about how to write API documentation follows from this idea.

This special purpose of _customer-facing documentation_ makes it different from other types of writing, including even some technical kinds of writing. For popular nonfiction outside of technical writing (with few exceptions) the above requirement doesn't apply. The same goes for scientific and medical writing.

Technical specs are much closer to home for people who work on APIs, but even specs are different — very different — from API documentation, because they are for internal readers as opposed to customers. Technical specs require readers to think about how something should be implemented in great detail, and sometimes invite the reader to discuss or disagree. They invite hard work, rather than relieve the reader of work.

Developers who use API documentation want to complete a task as quickly and efficiently as possible, preferably without frustration or confusion. (If developers complain about an API, it's likely that the documentation left them with unanswered questions or made it difficult to find the answer.)

Writing that’s directed toward ease-of-use results in well-written API docs that keep developers happy because the docs started with that end in mind.

Up next: Some practical ideas for making docs easy to use. (I promise I’ll come back to toolchains again, but the writing ideas are on deck.)