> 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.
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.
Suppose you want to teach the 'cat' concept to a very young child.
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 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.
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.
I don't think the problem is with intuition, though it's probably true that people don't realize that the absence of a freewheel is crucial to the function of a unicycle.
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.
Your comment reminds me of Lockhart's Lament[0] about how we (fail to) teach mathematics to children. It's a story about a world where we attempt to teach music in the manner that math is taught. Children rote-learn scales and musical theory from the beginning, building everything up until much later, when they are studying for a PhD, they finally are allowed to pick up a musical instrument and play for the first time, putting together everything they have learned over the years. The author compares this to how we learn mathematics and how only people in high-level applied math or engineering every actually get to use complex formulae in the real world and actually realize the inherent value of what they've been learning.
I recall "minimalism" in documentation being a theme during the 1990s, which I believe was influential in the design of documentation for Windows 95. I'd be interested in hearing more if anyone here knows about this.
"The part of your body that plays tennis doesn't understand English. " to quote Alan Kay paraphrasing Timothy Gallwey ("The Inner Game of Tennis").
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.
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 think that's a pretty high bar to say someone is proficient with a language. Children as young as 1-2 can effectively communicate their thoughts and feelings with others. I would speculate there are many functional adults with language skills not much better than a typical 10-15 year old.
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.
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.
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.
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.
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.
Pascal really said, "I would have written a shorter letter, but I did not have the time." The writer of the article is expressing a sense of humor known as dry.
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.
> 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.
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.
> 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.
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.
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.