Why I write long articles

I’ve been writing a long time and most of that has been technical documents, books, and articles. Most of them are quite long, but with good reason.

Much of what I have written has been for training or educational purposes in various formats, which tends to be structured. The first parts of the document generally discuss some type of background or foundational information, while later parts convey the details of the subject. There’s also some form of wrap-up or conclusion at the end. In some cases there are even exercises to perform.

I usually assume that my readers have little foundational information about my subjects, so I try to provide that in the early parts of whatever document I’m writing. I start with that foundational information and build on it until my readers have enough knowledge to comprehend the subject at hand. Many times I can do this in a single article or chapter, but other times it takes more.

For example, I wrote a series of articles on Bash programming for my website at Both.org. The first article introduces the series and offers a short discussion defining a shell. The second article defines the term, “program,” and proceeds to discuss short command line programs that can be created with Bash. Later articles build on that knowledge, and by the last article, the reader (the student) has built a template for future programs that includes a Help facility, a means to accept options at the command line, and testing strategies.

I follow this structure with nearly all of my writing, starting with basics and building layer upon layer of knowledge until the story is complete.

Because I primarily write about Unix, Linux, and open source software, and I find the history of those subjects to be particularly enlightening about how and why things are done as they are. That history is the best way I know to help myself and my readers understand the subject matter at hand. Personalizing the story with names and context makes technical writing more accessible and memorable.

An example of adding this historical context is the story of how the “pipe” was invented by Douglas McIlroy at Bell Labs in the early days of Unix. I include a brief mention of this in my article, The Linux Philosophy for SysAdmins, Tenet 02 - Transforming Data Streams, which includes a discussion of pipes, if you’re interested.

Another advantage of documents structured in this layered manner, is that the experiments I include allow my readers to feel comfortable with easy, simple commands before moving on to more advanced and complex ones.

The irony is that this is one of the shortest articles I’ve written. But it still follows the structure.