What is the subject of this document?

Probably the most common problem that I see in technical documentation is a failure to say upfront what the thing is that you’re documenting.

I feel that in most cases, one of the first pages of the documentation set should have a sentence early on in the page that says something like “[Product name] is …” and then a brief statement about what the product is.

(A statement like “[Product name] does …” can also work, and in some contexts is even better; but in many contexts that framing can continue to leave it unclear what the product is. For example, the statement “MyProduct makes your life immeasurably better” doesn’t tell the reader what MyProduct is.)

Without that kind of definition, someone who isn’t already familiar with the product can read dozens of pages of documentation and still not be sure what the product that they’re reading about really is. Is it an API? A web application? A platform? An image-processing chip? A wearable computer? A floor wax? A dessert topping? Who knows?

So do your readers a favor and tell them upfront what it is that you’re documenting.

Join the Conversation