API Documentation Writers: One Sentence Introduces Concepts
“The first sentence needs to be short and descriptive.”
For API documentation writing specifically, but also for technical writing in general, make the first sentence short and descriptive. It sounds so obvious but not everyone does it. This applies to the first sentence of any call, request, parameter, or any kind of description. It’s like an elevator speech for the call, much like “This call does X.” In one sentence, you give the readers enough information to determine if this is the right call for them. Technically, it gives enough information to determine if this call is the wrong one for them. Subsequent sentences can add progressively detailed information.
To demonstrate this point, you have to look no further than Wikipedia. For example, see the Wikipedia astatine page. Astatine is an obscure concept; many aren’t familiar with it. In fact, don’t look at this page yet, and tell me what astatine means. Now, look at the page. The opening sentence expertly and clearly places the concept: It’s a chemical element.
If readers were looking for absinthe or asinine, for example, they would know in one sentence that this page is not for them. The Wikipedia writer saved them time. They didn’t have to read any further to determine this was the wrong page.
In tandem with this idea, is the first paragraph should also be short and descriptive. Each sentence adds a progressive amount of detail. This page might be the right topic for the reader, but not necessarily having the exact information they want. Now, they can read the next sentence or two. The entire page continues in this format, each new section adding details. Personally, I think this is a perfect example. It also appeals to my nerdy spirit. This is probably all the information most people need to know about this element, short of being a scientist. If astatine ever appeared as a Jeopardy answer, the question would be somewhere in that paragraph. In four sentences, there are 13 fun facts. If only API documentation could keep up with something so interesting. But I digress.
Not only is all of this a good idea, but also not doing it this way violates several of my Robert’s Rules of Order for API Documentation Writing. Certainly, these are violations no writer wants to commit. These Rules of Order would be:
- Appeal to their laziness. Do things that save them time. Give them one sentence to read.
- This is technical writing. We shouldn’t have to guess what it means. Not giving them a summary means 1) they have to read more, and 2) they have to figure out what you’re talking about. Both are laziness violations.
- Never forget it is technical documentation. We’re introducing technical concepts and procedures. These may be new concepts so give context.
- We’re here for their convenience, not ours. Do as much for them as you can, even it’s hard for you. It’s more work for you upfront, but it makes it easier on them (a laziness conformance).