Keyboard with remodulated color map.

Some Thoughts About Writing Technical Material

In no particular order, as they occur....

Here are some things I have stumbled over while developing and presenting course material on Linux/UNIX, TCP/IP, and information security.

Hunter S. Thompson was right

"I found out then that writing is a kind of therapy. One of the few ways I can almost be certain I'll understand something is by sitting down and writing about it. Because by forcing yourself to write about it and putting it down in words, you can't avoid having to come to grips with it. You might be wrong, but you have to think about it very intensely to write about it. So I use writing as a learning tool."

— Hunter S Thompson, March 1990, in "Songs of the Doomed"

"I find that by putting things in writing I can understand them and see them a little more objectively. And I guess that's one of the real objectives of writing, to show things (or life) as they are, and thereby discover truth out of chaos. And now that I think on it a while, I think that the very fact that I write this letter and that I feel a need to write it shows the value of putting words in order on a piece of paper. For words are merely tools and if you use the right ones you can actually put even your life in order, if you don't lie to yourself and use the wrong words."

— Hunter S Thompson, July, 1958, in "The Proud Highway"

If you're interested in HST, you might want to see my pictures of places he lived in New York or in San Francisco.

Thomas Friedman is Also Right

"I don't mind using rhetoric," Friedman said. "I get criticized for that a lot: it's 'too cute,' too this or that. But I've never had a reader come up to me and say, 'That book was too easy to read. That anecdote went down too easily.' To simplify something accurately, you've got to understand it deeply."

— Thomas Friedman as quoted in "Profiles: The Bright Side", Ian Parker, The New Yorker, 10 Nov 2008,

William S. Burroughs Wasn't

In the introduction of the revised edition of With William Burroughs: A Report from the Bunker by Victor Bockris, we read:

As a child I wanted to be a writer because writers were rich and famous. They lounged around Singapore and Rangoon smoking opium in yellow pongee silk suits. They sniffed cocaine in Mayfair and they penetrated forbidden swamps with a faithful native boy and lived in the native quarter of Tangier smoking hashish and languidly caressing a pet gazelle.

Working in Pairs

I'm not going to try to sugar-coat this by calling it "teamwork", but at the same time I'm not going to criticize it by calling it "forcing people to share". The simple fact is that working together really is beneficial.

I have taught a few courses where a course that normally runs with people working in pairs is run with everyone having their own computer, always at the insistence of a corporate customer who insisted they wanted it this way. Those events all went poorly, as the labs were mostly silent frustration for the students.

My very non-scientific analysis is that we humans are not overly confident in our higher reasoning processes, but it seems that our typing skills are perfect and must not be questioned. When someone makes a simple but subtle typing error in a command or configuration file, they don't see their error and immediately wrongly conclude that their plan was flawed. Off they go on some wild goose chase. A lab partner would very likely have caught that error.

There's more to it than that.

First, see Hunter S Thompson's comments about how writing forces an organization of thought and thus understanding. Talking about something with a lab partner isn't as formalized and rigorous as writing, but it does force some organization and thought.

Malcolm Gladwell's book Outliers: The Story of Success includes a quote from Earl Weener, chief engineer for safety at Boeing: "The whole flight-deck design is intended to be operated by two people, and that operation works best when you have one person checking the other, or both people willing to participate. Airplanes are very unforgiving if you don't do things right. And for a long time it's been clear that if you have two people operating the airplane cooperatively, you will have a safer operation than if you have a single pilot flying the plane and another person who is simply there to take over if the pilot is incapacitated." Perhaps most surprising, he reports that the majority of airplane crashes occur when the more experienced crew member is in command. The problem is that the lower ranking pilot is less willing to say what's needed when an unsafe situation begins. Airplane flights are safest when the less qualified pilot has the controls and the more experienced pilot is monitoring the situation.

The Wall Street Journal discussed this in an article in August, 2012, Computer Programmers Learn Tough Lesson in Sharing. Companies like Facebook and EMC were advocates of paired programming, at least at the time of writing. Personal differences can get in the way, but many companies find it valuable.

Also see the U.S. military manual FM 3-0.5.222, "Special Forces Sniper Training and Employment", Chapter 1, paragraphs 1-18 through 1-20:

"1-18. Snipers conduct missions in pairs to enhance the team's effectiveness, provide mutual security, and maintain constant support for each other. Due to lowered stress, sniper pairs can engage targets more rapidly and stay in the field for longer periods of time than a single sniper due to lowered stress.
1-19. The more experienced of the pair will act as the observer during the shot. This method is especially important on a high priority target. The more experienced sniper is better able to read winds and give the shooter a compensated aim point to ensure a first-round hit.
1-20. Past experience has shown that deploying as a sniper/observer team significantly increases the success rate of the missions. With few exceptions, snipers who are deployed singly have shown a marked decrease in their effectiveness and performance almost immediately after the start of the mission. This decrease is due to the sniper becoming overwhelmed with concern for his security, the tasks to be accomplished, and his own emotions (fear, loneliness)."

How much detail? Just barely enough.

How much detail should you include in a technical course?

A better question might be: How much detail must you include?

The biggest risk is that the course author will include something esoteric because they think it's interesting. Often this is because the author just noticed or learned about it! Think about what this means — as a subject-matter expert writing training material, you have gotten by just fine without knowing this. While it should be interesting to you and your peers, it should not be necessary for the students.

I'm not talking about things that are mysterious to the all-too-frequent unprepared student. I mean things that are well outside the range of expected background for students coming into the course, and which use commands or command-line syntax that hasn't been and will not be explained in the current course. Worse yet, if they are obligated to run those commands for reasons that are not explained!

A second problem that I have encountered is when you are obligated to use a specific version of software on specific hardware, and some quirk of that combination causes problems. For example, some version of Red Hat Linux that happens to be the latest and greatest, but for which there may be some issues in configuring X on the customer's hardware. In that sort of situation, you have to decide: Is it really necessary to use that specific software version? Do the students need to learn that specific hardware/software combination, or are they trying to learn about Linux in general? Depending on the answer, you may find that you need to deal with a messy situation. In that case you really need to explain:

  1. The fundamentals of the technology involved — what is X, is the X service a part of the kernel or a user-space application, where is the X configuration file and how is it created, and so on.
  2. A brief description of the problem we need to work around.
  3. How that problem is detected, and how the workaround was figured out. Handled correctly, this last point will make the added time and distraction well worthwhile.

If something is necessary, they need to know about it.

If something is not necessary, they do not need to do it.

The exception I'm willing to make is bonus steps beyond the necessary ends of exercises. But they are bonus sections — material added to keep the faster ones occupied while the slower ones plod through the needed main steps. Unless you have far too broad a range of backgrounds and abilities in the course (and that is the fault of the training directors who so frequently send inappropriate people to courses), the people who do the bonus steps are those who likely know those out-of-bounds things already, or who are willing and able to quickly investigate the one-line manual pages to figure them out.

Less Is More

This is connected to the last one above. There is a limit to how much an adult human can take in during an hour, a day, and a week.

Four-day courses of about 6.5 hours each seems to be about as much as is really useful.

Yes, you can get people to occupy space in a classroom for longer than that every day and during a week. You may even be able to keep them conscious. But they are not going to learn very much at all after the 6th hour on each day and after the 4th day of that.