Evans on Patterns in Confusing Explanations

Software developer Julia Evans posts on a baker's dozen problems she has encountered in technical writing on a recurring basis:

Writing clearly is a LOT of work. A big part of what motivates me to put in the work to write clearly is my frustration with confusing technical explanations ("ugh, everything I read about Linux containers was SO confusing, I wish someone had just told me X Y Z ... ").

Yes. Evans is on to something here, and she brings back memories of some computer science courses I had to take as a complete neophyte to computing back in grad school.

Her discussion of C language header files particularly does so. Among the examples from just that discussion is the following:

Image by Mahdi Bafande, via Unsplash, license.

Pattern 11: No Examples

Another problem with the previous explanation of header files is -- there aren't any examples! Leaving out examples makes it harder for the reader to relate the new terminology to their own experiences.

Almost anyone who's ever written a C program has definitely used header files, so a simple example (like mentioning stdio.h) can really help.

In that header files example, I replaced

In modern C, header files are crucial tools ...

with an explanation that includes a simple example:

Almost every C program includes header files -- if you've ever seen something like #include at the beginning of a C program, stdio.h is a header file.

I remember being slightly mystified and annoyed by header files when I first encountered them. Something like this -- and the further elaborations she gives elsewhere -- would have helped me a lot then to (a) better understand the language, (b) remember why header files were important, and (c) not be annoyed, and maybe even enjoy programming, to the extent that I needed to do it. As it was, including header files was something of a mysterious ritual for me for a while, as I was too overwhelmed to tackle it. (Perhaps I asked and got a bad explanation: I don't remember anymore.)

In any event, Evans doesn't just list the patterns; she explains what's wrong with them and what one should do instead.

There's a definite So it's not just me! in her post for me, but I also appreciate seeing why so much material related to computing is so difficult -- that is, when it isn't so geared to a beginner as to be nearly useless. (And perhaps each extreme exemplifies her Pattern 2, having inconsistent expectations of the reader’s knowledge.)

My pet theory had been that technical writing is often aimed at an audience more familiar with the subject matter, and that an author can make assumptions not always warranted for a general audience. I still think that's often true, but Evans shows/reminds us that it's hard to do well. Indeed, her patterns are worth considering for adoption as a Do Not Do/What to Do Instead list by non-technical writers as well.

-- CAV