
Technical Writing: Learning from Kernighan - kqr
https://two-wrongs.com/technical-writing-learning-from-kernighan.html
======
combatentropy
> The tutorial throws the user straight into the experience of using awk.
> There is no theoretical discussion first; there are no installation
> instructions; the first thing you see is an input example and a short
> program doing something with that input. They even get to the expected
> output on the very first page.

Babies learn a language by hearing you talk. In other words, by example. No
one has become fluent in a language through theoretical discourse and
grammatical diagrams.

That is counterintuitive. You would think you would learn better by having
someone explain it to you, instead of throwing a mish-mash of examples your
way. But that's not the truth. The truth is we learn by example and practice.
Eventually you want the explanations, to round out your understanding. But it
doesn't make sense until you have got your hands dirty.

So that's a lesson for anyone wanting to teach anything. It's okay to have a
little introduction, but try to get to concrete examples as soon as possible.

~~~
svat
Indeed. And this applies to mathematics too. Here is Ralph Boas, in _Can We
Make Mathematics Intelligible?_ following his own advice:

> Suppose you want to teach the 'cat' concept to a very young child. Do you
> explain that a cat is a relatively small, primarily carnivorous mammal with
> retractable claws, a distinctive sonic output, etc.? I'll bet not. You
> probably show the kid a lot of different cats saying 'kitty' each time until
> it gets the idea. To put it more generally, generalizations are best made by
> abstraction from experience.

(See also Tim (Sir Timothy) Gowers on Examples first:
[https://gowers.wordpress.com/2007/10/19/my-favourite-
pedagog...](https://gowers.wordpress.com/2007/10/19/my-favourite-pedagogical-
principle-examples-first/) and
[https://gowers.wordpress.com/2007/10/24/examples-first-
ii/](https://gowers.wordpress.com/2007/10/24/examples-first-ii/))

(I frankly think this applies to the accursed phenomenon of monad tutorials in
Haskell too ([https://stackoverflow.com/questions/3261729/monad-in-non-
pro...](https://stackoverflow.com/questions/3261729/monad-in-non-programming-
terms/3261837#3261837)), but some disagree.)

~~~
theoh
The idea of teaching using extensional definitions (an expanding list of
examples) is fine, but I came across a weird case of it at a bicycle repair
workshop a few years ago.

It's a bizarre example, but it went like this.

Audience: what's a fixed gear bike?

Repair guy: it's uh, it's like a unicycle, for example...

In that scenario an intensional definition is really the way to go. I don't
understand how that bicycle repair guys mind worked at all.

~~~
kqr
Having ridden both fixies and unicycles, the example makes total sense. "It's
like a pennyfarthing" works too. The issue is that examples are meant to
leverage the recipients intuition. Very few people have intuition for
unicycles and pennyfarthings, so the examples fall flat.

That said, "It's like a children's unicycle" would probably count as a valid
example too, and refers to something people may have intuition for. But it may
also stress the wrong parts of the example. We want to convey the sense of
direct drive, not circus prop.

~~~
lloydde
> That said, "It's like a children's unicycle"

Tricycle? Or I’m very interested in a culture where children’s unicycles are a
common thing.

~~~
kqr
Yes, tricycle, of course. If anyone figures out where this children's unicycle
culture is I may want to move there.

------
mediocrejoker
Kernighan also has a very well written book called Understand the Digital
World, which is an introductions to computer and network technology for a non-
technical person. It touches on binary, assembly language, and a few higher
level programming languages while emphasizing the general idea of what a
computer can and cannot do. It also includes very up to date discussions of
how networks work (at a high level) and online privacy and, encryption and
security.

His ability to explain highly technical concepts to someone with no assumed
computing background in concise and lucid prose is really impressive.

~~~
hackermailman
Most people when they ask me where they can learn basic things I recommend
that book. It even covers basic programming in js.

------
mauvehaus
I'll call out another book for being a great piece of technical writing: Unix
Shell Programming[0]. It similarly follows the structure of introduction,
complete description (if not full-depth out of necessity), intermediate, and
advanced techniques, and some reference material.

The running example throughout the book is to build an address book program
called "rolo" (Rolodex, get it?), and the authors do a nice job of
progressively building the features while illustrating useful techniques that
are generally applicable.

I've not read the 3rd edition, but I can vouch for the fact that the 2nd would
be getting a little dated by now. Still, it's well-written, well-structured,
and a great introduction to most of the shell concepts that you use.

[0] [https://www.amazon.com/Unix-Shell-Programming-Stephen-
Kochan...](https://www.amazon.com/Unix-Shell-Programming-Stephen-
Kochan/dp/0672324903)

------
actuallyalys
I think this is excellent advice. From the small amounts I've read, the other
thing these books do well is connect what the reader already knows to what's
being taught.

My only quibble is that I suspect minimalism is more a matter of taste than a
widely applicable principle of solid technical writing. I've learned a lot
from minimal books, but I've also learned a lot from books that incorporate
screen shots or full-color illustrations. This isn't to say minimalism didn't
work well for Kernighan-just that it's not as generalizable as the other
principles.

FYI, You can read both the The C Programming Language [0] and The AWK
Programming Language [1] at the Internet Archive.

[0]:
[https://archive.org/details/TheCProgrammingLanguageFirstEdit...](https://archive.org/details/TheCProgrammingLanguageFirstEdition)

[1]:
[https://archive.org/details/awkprogrammingla00ahoa](https://archive.org/details/awkprogrammingla00ahoa)

~~~
copperx
A counterpoint would be Knuth's The TeXbook. In that book, Knuth explains
every feature of TeX in excruciating detail, without being boring. He could
have made the book 1/4 the size, but the book would have been worse for it.

~~~
userbinator
The TeXbook has a lot of examples too, and Knuth makes very good use of the
fact that it was _itself_ written in TeX to illustrate the functionality.

------
innocentoldguy
I agree with the observations made in this article, with regards to structure
and content. As a consumer of technical documentation, my top five pet-peeves
are:

1\. Long histories about the origins of the technology. I couldn't care less.
For me, the purpose of reading a technical book is to accomplish something
technical. Historical anecdotes, while interesting, don't help.

2\. Overly complex code samples and projects. It is really easy for me to read
a simple example and extrapolate that into something greater. It is more
difficult to decipher a complex example, reduce it to its basic parts, and
then extrapolate the few bits I need. This is why I don't like _project books_
, where the author guides me through developing software to run a video store,
for instance. The code samples are not self-contained and the likelihood I'm
going to write video store software is literally zero. It is possible to
explain complex ideas with short, self-contained code. I think Avdi Grimm does
a good job of writing this kind of documentation.

3\. Chapters that cover the installation of the technology on every operating
system known to man. I'd rather Bing that information or have it in an
appendix. There is no need to waste Chapter 2 delving into it.

4\. API or library documentation that doesn't include code samples and clear
descriptions of what I can pass in and what I should expect out.

5\. Formatting. For example, I never liked Wrox books because of the
minimalistic whitespace. The books probably contained excellent information,
but the formatting was hard to look at and didn't leave any space for me to
write annotations.

During my career, I've found that the books that address these five issues are
the books I tend to keep. They also seem to be the most popular in their
respective communities.

------
drsopp
From the article: Blaise Pascal summarised it by saying that “I would have
written you a shorter email, but I did not have the time.”

That’s impressive, as he died over 300 years before email was invented.

~~~
commandlinefan
That's why it was only just now delivered.

~~~
jl2718
Imagine how long it would have taken if it were shorter.

------
mcguire
There's quite a series of books co-authored by Kernighan, all excellent. Three
others are _The UNIX Programming Environment,_ _Software Tools_ (in Ratfor and
Pascal), and _The Elements of Programming Style._

They are classics for many reasons, including how far you get in such short
books.

~~~
vram22
Totally agree. Just found a few more from the Wikipedia page about Kernighan:

[https://en.wikipedia.org/wiki/Brian_Kernighan](https://en.wikipedia.org/wiki/Brian_Kernighan)

The Elements of Programming Style (1974, 1978) with P. J. Plauger

Software Tools (1976) with P. J. Plauger

The C Programming Language (1978, 1988) with Dennis M. Ritchie

Software Tools in Pascal (1981) with P. J. Plauger

The Unix Programming Environment (1984) with Rob Pike

The AWK Programming Language (1988) with Alfred Aho and Peter J. Weinberger

The Practice of Programming (1999) with Rob Pike

AMPL: A Modeling Language for Mathematical Programming, 2nd ed. (2003) with
Robert Fourer and David Gay

D is for Digital: What a well-informed person should know about computers and
communications (2011)[12]

The Go Programming Language(2015)[13]

Understanding the Digital World: What You Need to Know about Computers, the
Internet, Privacy, and Security (2017)

------
blt
> _You often see a whole chapter in the beginning devoted to explaining the
> philosophy behind the technology, rather than letting the user get a feel
> for the philosophy themselves, by doing._

I agree that this is annoying. As an author, it's very tempting, since you
want to explain why your solution is better than all the other solutions that
came before. But the vast majority of readers won't know anything about the
other solutions and just want to know what your thing does. The "Avail"
language page posted yesterday [1] was a perfect example.

[1]
[https://news.ycombinator.com/item?id=17150346](https://news.ycombinator.com/item?id=17150346)

------
ken
"First of all, both books are very short"

Both tools are small and self-contained, because they date from an era when
that was the style. Most programmers don't seem to want that any more. ("Those
days are dead and gone and the eulogy was delivered by Perl.") They want
"batteries included".

Does anyone believe that even Kernighan could write a short book covering
C++17?

The most important first step, then, is picking a subject matter which it's
possible to isolate. Everything has become so entangled, though, that I'm not
sure how to do that any more.

~~~
AnimalMuppet
> Does anyone believe that even Kernighan could write a short book covering
> C++17?

I suspect that Stroustrup's "A Tour of C++" is the shortest C++ book possible.
The 2013 edition ( _not_ covering C++17, obviously) has the index beginning on
page 171 - astonishingly short for the complexity of C++11.

Interestingly, the quote that heads the first chapter [Edit: preface, not
first chapter] is "If you wish to instruct, be brief", quoting Cicero.

------
lunchladydoris
This post and comment thread [0] got me reading The AWK Programming Language
this week, and I have to concur with the author. What a great book!

After just the first chapter I feel I understand AWK, the kinds of things it
can be used for, and how to get started on some simple tasks immediately.

[0]:
[https://news.ycombinator.com/item?id=17140934](https://news.ycombinator.com/item?id=17140934)

------
vram22
I liked the appearance of the site. Very clear and easy to read.

------
mseepgood
I love his book "The Go Programming Language".

~~~
vram22
Wow, I didn't realize that makes it _four_ very good books that Kernighan has
been involved with: The C Programming Language (by Kernighan and Ritchie), The
Unix Programming Environment (by Kernighan and Pike), The AWK Programming
Language and The Go Programming Language. I have three of the books in hard
copy (and had the first two books for years, in fact, bought multiple copies,
because the earlier ones wore out); the only one I do not have is the AWK
book. Along with many others, I think they are (all the ones I have read)
great examples of technical writing. I've conducted training for customers
using the first two books (on C programming and Unix respectively), and once
got a present (a quartz wall clock) from one customer (a large public sector
Indian company) whose participants thought I conducted the training well. I
still have the clock.

~~~
AnimalMuppet
Don't forget "Software Tools" by Kernighan and Plaugher.

~~~
vram22
Good point, thanks. I haven't read it, but have read good reviews of it. A
classic, I believe.

~~~
vram22
Also see my more recent comment in this thread:

[https://news.ycombinator.com/item?id=17163276](https://news.ycombinator.com/item?id=17163276)

------
cnbcnn
Blaise Pascal? E-mail?

~~~
ramblerman
not sure why you are being downvoted. It's a funny typo

~~~
ColinWright
It's not a typo, it's called "humor".

------
DoofusOfDeath
I must be tired today, I misread the title as "Technical Writing: Learning
from [Sarah] _Kerrigan_."

FWIW, I would watch _the hell_ out of that tutorial.

~~~
AzzieElbab
I wonder who wrote the zerg rush ml/AI paper

