60 ms·
Technical Writing: Learning from Kernighan
- lunchladydoris 8y agoThis 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
- actuallyalys 8y agoI 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/TheCProgrammingLanguageFirstEdition https://archive.org/details/TheCProgrammingLanguageFirstEdit... [1]: https://archive.org/details/awkprogrammingla00ahoa https://archive.org/details/awkprogrammingla00ahoa
- copperx 8y agoA 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.
- Koshkin 8y agoYes, opposite sides sometimes converge.
- userbinator 8y agoThe 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.
- combatentropy 8y ago> 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.
- Benjammer 8y agoYour 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. [0]https://www.maa.org/external_archive/devlin/LockhartsLament.pdf https://www.maa.org/external_archive/devlin/LockhartsLament....
- deleted 8y ago[deleted]
- svat 8y agoIndeed. 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-pedagogical-principle-examples-first/ https://gowers.wordpress.com/2007/10/19/my-favourite-pedagog... 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-programming-terms/3261837#3261837 https://stackoverflow.com/questions/3261729/monad-in-non-pro...), but some disagree.)
- mauvehaus 8y agoI'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/dp/0672324903 https://www.amazon.com/Unix-Shell-Programming-Stephen-Kochan...
- drsopp 8y agoFrom 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.
- combatentropy 8y agoPascal 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.
- commandlinefan 8y agoThat's why it was only just now delivered.
- jl2718 8y agoImagine how long it would have taken if it were shorter.
- deleted 8y ago[deleted]
- DoofusOfDeath 8y agoI 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 8y agoI wonder who wrote the zerg rush ml/AI paper
- cnbcnn 8y agoBlaise Pascal? E-mail?
- ramblerman 8y agonot sure why you are being downvoted. It's a funny typo
- ColinWright 8y agoIt's not a typo, it's called "humor".
- ken 8y ago"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 8y ago> 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.
- innocentoldguy 8y agoI 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.
- mseepgood 8y agoI love his book "The Go Programming Language".
- vram22 8y agoWow, 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 8y agoDon't forget "Software Tools" by Kernighan and Plaugher.
- mediocrejoker 8y agoKernighan 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 8y agoMost people when they ask me where they can learn basic things I recommend that book. It even covers basic programming in js.
- mcguire 8y agoThere'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 8y agoTotally 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)
- vram22 8y agoI liked the appearance of the site. Very clear and easy to read.
- blt 8y ago> 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