If You Ask a Rhetorical Question, Answer It, Right Away

If you pull your readers into a topic by asking a rhetorical question that’s perfectly acceptable as a writing style.
But if you do that, you’d better answer your own question right away. Otherwise some of your readers can be really frustrated.

Rhetorical questions increase the stakes. They introduce a tension that needs to be relieved by delivering the promised answer. You cannot assume that the readers know the answer to such a question.
Rhetorical questions that are left unanswered is a sign of sloppy writing at best. Some reader may even construe it as “disrespect for the audience.”

Here is an example:

The paragraph opens up with a wonderful teaser: “So, what is Git in a nutshell?”
But then writer disregards her own question and forgets to answer it. No where on the page is there a definition of Git “in a nutshell.” The overall impact is one of frustration and unrealized user expectation.

If you’d like to maximize the User Experience (UX) of your documentation don’t forget to answer your own rhetorical questions. The sooner the better.