One problem I see with a lot of technical writing on the web, particularly from authors without any formal training in writing on technical subjects, is that examples are undervalued. A lot of writing contains formal descriptive text while containing too few examples that demonstrate reality (or none at all).
Naturally, the reverse problem does appear sometimes, where writers overvalue examples at the expense of formal definitions and abstraction. A lot of the time that’s preferable to no examples, but sometimes, as in every single math textbook I used before I got to college, it’s just as befuddling. Such an arrangement obligates the reader to guess at specifications and rules. Thankfully, I run into that problem with far less frequency than I encounter stuff that’s missing much needed examples.
I don’t think there’s much of a case against examples, even if specific examples might be found lacking. Examples are often fun to write, because they’re usually easy to do (with a few notable exceptions, like screenshots). They’re good to write because they deliver a lot of information in a digestible way.
For example, consider HTTP requests and responses. HTTP requests and responses are how web browsers and web servers communicate. They’re well-defined and they’ve been in use for more than a decade. Although most people don’t know anything about them, they’re not hard to understand. But a description without examples is awfully dry. Here’s my attempt:
An HTTP request is a message (for our purposes, some lines of plain text) to ask for some data from a remote HTTP server. An HTTP request contains a request line (the first line), header lines, an empty line, and an optional message body. The request line contains the method type (one of HEAD, GET, POST, PUT, DELETE) to be performed on the desired resource, the URI of the desired resource, and the protocol version. A header line contains a header name, a colon and a space, and the contents of the header.
An HTTP response is a message which reports on the fulfillment of a received response. An HTTP response contains a status line (the first line), header lines, an empty line, and the response body. The status line contains the protocol version, a status code, and an accompanying reason phrase.
In a word, boring. It’s a very brief summary of the canonical formal description of HTTP, RFC 2616, but it’s mostly accurate. With a couple of extra details (e.g., a list of valid status codes and reason phrases) you could write a valid HTTP request or response with the information above. Though I’ve technically given you all you need, it’s likely that your first (and second and third) attempts to create valid request or response wouldn’t look right. There’s a lot of detail to capture in prose, but an example would clear things up nicely.
So, here’s an example HTTP request, specifically to download the Google home page:
GET / HTTP/1.1 User-Agent: HTTPExample Host: www.google.com
A lot of readers would be satisfied with just that, but writers can provide even better examples by annotation. Here’s the same thing, but with some explanatory notes included:
GET / HTTP/1.1 # "GET" the page at the root (/) using HTTP 1.1
User-Agent: HTTPExample # Program making the request header
Host: www.google.com # Host name header
# An obligatory blank line
We can do the same with an HTTP response (with some unneeded clutter removed for simplicity’s sake):
HTTP/1.1 200 OK # Status line with protocol version, status code, and phrase
Date: Mon, 25 Apr 2011 22:22:47 GMT # Date header
Content-Type: text/html; charset=ISO-8859-1 # Content type and encoding header
Server: gws # Server ID header
# An obligatory blank line
<!doctype html> # Response body
<html>
<head>
<meta http-equiv="content-type" content="text/html; charset=ISO-8859-1">
<title>Google</title>
<!-- trimmed for brevity, but I could go on -->
After all that, I haven’t added a ton of new information about HTTP requests. Again, with the exception of a few details, there’s not much there that wasn’t in the prose description. But examples and annotations can help readers “GET” it that much easier, so don’t forget to include them in your documentation.
Excellent point. I always consider examples and tutorials as “nice to haves” when we aren’t given enough time to work on a deliverable (i.e. the things that we drop first). The reality, however, is that they are really important, and (in my opinion) help take documentation from good to great.
It’s quite useful to have an example or (even better) an outright template when constructing something that needs to adhere to a specific format. Annotations make the example FAR more useful.
Extra points for using the word “befuddled” in this post. A picture popped into my head of a guy looking at a math textbook, scratching his head while question marks popped up around him.