Technical Writing: Learning from Kernighan
two-wrongs.com
two-wrongs.com
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.
[0]https://www.maa.org/external_archive/devlin/LockhartsLament....
> 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... and 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...), but some disagree.)
It helped me grok monads after I had a hazy understanding of them for a while.
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.
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.
Tricycle? Or I’m very interested in a culture where children’s unicycles are a common thing.
The problem is that a single example which differs on multiple dimensions from the "standard" bike (e.g. number of wheels, stability characteristics, steering, holonomic vs nonholonomic maneuverability) is highly ambiguous.
Given the context, my mind jumped to the other `cat' and how I would explain it, before I read the rest of the paragraph... and I started imagining the analogy of multiple trains waiting to enter a single track, one after another.
To put it more generally, generalizations are best made by abstraction from experience.
In other words, the value of an abstraction is best understood by seeing the cases it abstracts over. A stark contrast to the "always abstract even if you don't think you need to" attitude that is unfortunately often taught in computer science courses, which leads to overuse of abstraction and the accompanying proliferation of accidental complexity.
The origin text for this I believe was "The Nurnberg Funnel" by John M Carroll (https://mitpress.mit.edu/books/nurnberg-funnel) -- but I haven't read it. I have read a book of essays following up on it, "Minimalism Beyond the Nurnberg Funnel" https://mitpress.mit.edu/books/minimalism-beyond-nurnberg-fu..., which I found quite inspiring.
Both of the examples used here are older than that, which is also intriguing.
Babies take at least ten to fifteen years to become truly proficient with a language and that includes a lot of formal learning. Once a first language has been acquired the process of learning becomes much easier.
Examples are very good, though. The Python documentation is usually very good at this. Examples often lead the sections with the exact details following.
I don't think all explanation is redundant and counter-productive, but a lot of it is. I think it is useful to demonstrate how and explain why. If a stufmdent can internalize the correct motivation of why that can help choose which skill or technique to apply.
His ability to explain highly technical concepts to someone with no assumed computing background in concise and lucid prose is really impressive.
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...
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...
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.
That’s impressive, as he died over 300 years before email was invented.
They are classics for many reasons, including how far you get in such short books.
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)
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.
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.
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.
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.
FWIW, I would watch the hell out of that tutorial.