WORK:Technical Writing; Breaking It Up

Private feedback on the last letter included a suggestion that I try to explain how to break down a complex topic and explain it in plain english.

Well. I just went and looked through one of my articles at random, to try to find a paragraph I could use for an example. This article builds on five previous articles - every paragraph includes jargon that was explained in the earlier articles!

So that's one of my tips: don't be afraid to use jargon. Just make sure it's jargon you've explained, or jargon your audience can be expected to know.

Here's a paragraph from a recent article:

(Earlier in the article, I explained that HTTP is related to web pages, and provided the RFC code for the HTTP specification - so the reader can go look it up, and do research for themselves. At the end of the article, I link to the RFC. (My articles are on the World Wide Web.) In this paragraph, I provide the section number that the paragraph refers to.)

"The HTTP/1.1 specification (section 13) has strict requirements for caches: It requires them to provide semantic transparency--returning a cached response should provide the same data as would be retrieved from the origin server; and it calls for them to read freshness requirements provided by origin servers and clients."

(A cache is a temporary storage place, in computing as well as in plain english. An HTTP cache is a temporary storage place for web pages, so they can be closer to the person requesting them & can be served faster & more cheaply.)

In this paragraph and the ones that follow it, I am trying to reassure a system administrator that making his site's web pages friendly to http (web page) caches won't change how the pages display to the end user. I do this by explaining what the specification requires of caches.

I start by explaining semantic transparency. To fully explain semantic transparency would take several paragraphs, and the RFC does. But to briefly cover it, I used a clause. Essentially, I tried to look at the essence of semantic transparency - to pull a one-sentence hook out of it. It's the same task that you use when you try to provide the one-sentence answer to 'so what's your book about?'

So semantic transparency is about ensuring that the web page returned from the cache is the same as the web page that would have been returned from the origin server.

If you pretend you knew what 'cache' and 'origin server' mean, and know that 'returned' is shorthand for 'returned in answer to a request for a particular page' that sentence makes sense to pretty much anyone.

I go into more detail about freshness requirements later in the article, so I won't try to explain that here - I included it in the paragraph to reassure system administrators that they hadn't been left out of the specification.

So some tips:

Don't try to explain it all at once. You have no hope of it.
Don't try to explain it all in a single article. You have no hope of that, either.
Know your audience. If they should know that an HTTP cache caches the World Wide Web, don't explain it to them. For the few who don't, provide enough hints that they can pick it up by context - and provide resources they can use to learn the fact.
(This may be more of a 'how to write concisely' tip)
Make each paragraph do double or triple duty. The one in my example reassures sysadmins that caches won't hurt them, teaches them about semantic transparency, flags that freshness is likely to be discussed later, and tells them where they can learn more about the topic.
Break the topic into pieces that are small enough to explain without digression. The phrase 'the web page returned from the cache' is readable. The alternative is not:
'the web page (a common term for the images and text displayed in an HTTP client or browser) returned, in response to a request from an HTTP client or browser for a specific, named page, from the http caching server between the http client or browser and the origin server'.

Eeesh. Break it up! Explain only one thing at a time. If that means that occasionally the reader will have to look further into the article for answers, so be it.
Try to explain things in sequence. If you possibly can, explain a term before you need to use it. Sometimes things are interdependant, or you need to do something early on in the article (like reassure sysadmins). In those cases, explain things that you can explain in a clause, and use the most descriptive-from-context language you can for the rest. Then explain those later.

If the reader can see that you DO explain stuff, they'll be willing to trust you on other things.

If they can make a good guess about the meaning of things, they'll be willing to go with you for the moment. Try to provide the explanations fairly soon, though - not being sure is like an itch they can't scratch.

That'll do for the moment. Ask for more later. :)

Workshop:Technical Writing: breaking it up