Preferably openly available content so that everyone can access (blogs etc.)
Focus is on "overall" score: tone, presentation, etc. as opposed to "very technically advanced" (although advanced examples fully welcome)
EDIT: awesome suggestions so far - should add that it doesn't have to be programming or even computer related... cookbooks count!
Other books by him.
1. The UNIX programming environment
2. The Practice of Programming
3. The Go Programming Language
The Elements of Programming Style
Software Tools / Software Tools in Pascal
I have read Elements and Software Tools in Pascal, and while partially definitely outdated ("avoid FORTRAN's three-way if"), excellent writing. Especially Software Tools in Pascal, which in large parts describes and explains source code; I was very impressed by the way the descriptions added lots of insights on top of just the code. Kernighan also manages to smuggle subtle bits of humour into texts about otherwise dry topics.
The Go book was mostly written by Alan Donavan, according to Kernighan anyway (as stated in some interviews), but he's not the bragging sort so he might be underselling his contribution.
I enjoy clowning around and joking in personal interactions (if appropriate) and used to do it in my writing, but have come to believe that the humble, dry, concise style of the works mentioned above is most suitable and clearest for technical writing addressed to an unknown audience.
I learned C from “Practical C Programming” by Steve Oualline. I remember reading it on bus rides home from work and just itching to try out the code myself. I loved that the author motivated many of the exercises with the weird corners of C that eventually bite you if you only have a naive understanding of the language. There’s even a fun one on the cover itself.
And, of course, Knuth.
Improving almost anything by George Box blew my mind. As children and even as university students we have been lied to. We have been told that experiments must be carried out one at a time to assign effects. This is patently false. In fact, we miss out on potential interaction effects (think temperature and time in cooking) by using one factor at a time experimentation. In this book he discusses many now old but fundamental techniques by which large improvements in models can be gained with minimal data. It has helped me in my career immensely and made me aware of many usual methods and fields of study.
In fact i would go so far as to say it was directly responsible for the success of Microsoft Windows.
[0]https://www.wiley.com/en-gb/Improving+Almost+Anything%3A+Ide...
My recommendations would be Hilary Putnam, Nelson Goodman, and W.V.O Quine.
A paper I’m currently reading, which was seminal in phenomenology, is “ The Phenomenology of Cognition: Or What Is It Like to Think That P?”[1] by David Pitt. Really nice example of a well-formed thesis.
> A number of philosophers endorse, without argument, the view that there’s something it’s like consciously to think that p, which is distinct from what it’s like consciously to think that q.
I've re-read it umpteen times and by brain still refuses to parse it. This is not, IMHO, articulating anything clearly or precisely.
For what it's worth, in the expression "to think that p", "p" is meant to designate any arbitrary proposition; e.g., if p is the proposition "it is raining", then "to think that p" expands to "to think that it is raining". (Likewise q is some other arbitrary proposition.) "There's something it's like to X" is a conventional way of saying that (under normal circumstances) X causes or corresponds with a conscious experience. In the quoted sentence "consciously" is a little superfluous, but the paper is dealing with phenomenology (the study of first person conscious experience), so I'm assuming the author added it for emphasis.
It's a pretty technical paper and there's a lot of terminology and assumptions of background knowledge. I definitely find myself reading sentences over and over, but I tend to assume that those issues are more the result of my lack of understanding than of clarity of writing.
The other part is the "there is something that it's like to" thing, which is kind of a set phrase/idiom in philosophy, meaning "this is a thing that can be experienced". Sentience is often defined that way: there is something, even if you can't describe it any more precisely, that is "this is what it's like to be a human", but not "this is what it's like to be a rock".
(This comment is intended as an explanation of that mess of a sentence, not a defense of it.)
“John Adams” by David McCullough. Possibly the best historical bio ever.
“The Making of the Atomic Bomb” by Richard Rhodes. The best recounting of the founding of Los Alamos.
“Hackers” by Steven Levy. The best book on the birth of creatine coding.
“The Soul of a New Machine” by Tracy Kidder. The best tale of hardware design I know.
“Masters of Doom” by David Kushner. The best book on the early days of gaming, esp. about Carmack and Romero.
Anything by Eric Raymond, esp. “The Cathedral and the Bazaar”.
I think it's remembered fondly mostly because it was an effective bit of advocacy written during a time period people view fondly.
If you leave aside security bugs, is Linus’ law still invalid?
Any reference to any material on this?
So many of these comments are recommending dry prose, Julia’s writing is fun and sympathetic about how hard all this junk is
I’ve found myself writing technical stuff in her voice a lot these days and I think it’s made my documentation more accessible
Over the past few years, Prisma has been quietly building a complete zero to advanced guide to databases that I've started to refer people to and use as reference myself. It stands out to me because it is focusing on a broader topic than what you typically find in docs, it's written simply, it is super comprehensive, and it's not trying to sell something.
Michael Kerrisk
Author of the Linux Programming Interface, innumerable man pages, and many other projects.
Absolutely, without question, the best longform technical writer. Reading his books, where he gets to exercise all of the skills in terms of sequencing, layering, explanation, repetition, etc is like receiving an architectural download from the universe.
Will also like others cite Knuth, whom I used to read just for relaxation that his orderly brain would induce in mine, and Stallman- the technical writings- who for all his flaws was and is an exceptionally gifted explainer.
Covers some of the history of the Linux/Unix API, describes it in detail, has plenty of examples, compares different APIs that do similar things so you can make an informed choice (e.g. System V vs. POSIX message queues).
If any book in this list stands out for me, it's probably this one. It might be partly due to the surprise factor of how enjoyable and well-written a 1000+ page, near-reference book is.
Someone also mentioned Julia Evans [2]. She makes complex topics more approachable.
One of the most complete (and useful!) books about an area of study I've found is The Art of Electronics[2] by Horowitz and Hill. They point out all the traps that are likely to be encountered by an engineer working with the components as they describe them, along with the various trade-offs.
1 - https://archive.org/details/bitsavers_borlandturVersion3.0Re...
But as an example of good technical writing in general, I don't think it holds up so well. The style is extremely discursive and there is little structure except for the chapters, many of which are 50 page monoliths. So to me it's more like a work of literature that you take at the author's pace, not a useful repository of technical information for someone whose time and focus are more limited.
Don't get me wrong, I like texts that read well and gradually unfold into a deeper understanding of their subject matter, but in technical writing I also like support for a reader who needs to understand specific aspects of a subject in a form that is convenient to them as a student or professional
> I like texts that read well and gradually unfold into a deeper understanding of their subject matter
Sounds good! Will check it out.
Edit: formatting.
A lot drier but top marks for clarity: “Linear Algebra Done Right” by Axler.[2] It got me through both undergraduate and PhD math degrees. When something was confusing in a lecture or another textbook, I could always return to Axler for the most direct path from ignorance to understanding.
[0]: https://www.amazon.com/Chaos-Making-Science-James-Gleick/dp/... [1]: https://www.amazon.com/Information-History-Theory-Flood/dp/1... [2]: https://linear.axler.net/
In the 1980s the children's publisher Usborne published computing books for young readers and a few years ago they made the books available for free download. The books use illustrations extensively to explain concepts. Not only are these books well written with clear, concise explanations, they are also more readable and enjoyable than many programming and computing books published for adults today.
Anyone writing a technical guide (of any kind) would benefit from reading these as a source of ideas and inspiration:
1. You had to type the code in to get it working. There would inevitably be errors which I had to debug and fix that taught me that skill.
2. I had GW-BASIC on DOS while the book used another dialect and it had some "porting guides" in the appendix. I sort of learnt some lower level details from porting the programs to work on my computer.
I also feel that they had a friendly but "gloves off" approach to teaching. They treated their (child) audience as smart, intelligent, small adults rather than kids who needed to be entertained to learn anything and achieved something which, I feel, is missing in many modern books.
1. What was your mathematical knowledge when you read this book?
2. What did you gain from working through this book?
As a bonus, you get more examples in the comments—kind of like Stack Overflow, but attached to a particular feature or process of PHP.
fwiw I would recommend all programmers read Game Programming Patterns even if they have no intention to ever write a game.
Mastering The Art Of French Cooking, Julia Child
These books are a combination of background information, recipe, and step by step instruction. So these are more a reference of how to write an implementation guide or Runbook, rather than how to describe an API or present architectural documents.
I also really liked Mastering Algorithms With Perl, and any of the For Dummies books on technical subjects.
- Namespaces in operation, part 1: namespaces overview — https://lwn.net/Articles/531114/ (2013)
You can see their entire kernel archives here[3]. And as to their excellent conference coverage, you can browse conferences by year[4]. Most recently, here's[5] their roundup of "Linux Storage, Filesystem, Memory-Management and BPF summit".
[1] https://lwn.net
[2] https://lwn.net/Articles/531114/#series_index
The PostgreSQL documentation is pretty fabulous. It’s well organized, complete, clear, and purposeful. You can read it like a textbook from page 1, or dive into it as a quick reference.
Great job of providing low level details contextualized in a high-level narrative. He’s also got these amazing fantasy maps of the fictional landscape of data architecture: https://martin.kleppmann.com/2017/03/15/map-distributed-data...
Google Developer Documentation Style Guide https://developers.google.com/style/
Microsoft Style Guide https://docs.microsoft.com/en-us/style-guide/welcome/
(minor disclosure - I worked in the CS department at UCB when he was a PhD student but I didn't really know him, and I strongly doubt he remembers me.)
https://www.sqlite.org/fileformat.html
Much better than other file format docs I've read, covers almost all the corner cases well, broken up into logical sections, uses tables for data formats when that makes sense, etc.
What I found particularly unique about it was the way it highlighted changes made to the language since the first edition. Instead of having a notes section at the back or asides scattered throughout, it's structured like a redlined document (although much easier to read). Paragraphs that are no longer relevant are marked with a dotted vertical line in the margin, while additions are marked with a solid vertical line. Typically you'll see a removed section immediately followed by an addition that'll note something to the effect of "X3J13 voted to remove this from the language in July 1988..." and it'll go on to explain why that happened. Reading about all of the votes really hammered home the fact that Common Lisp was a compromise between many different organizations and dialects. So not only did it help me better understand Common Lisp, it helped me appreciate why Common Lisp is the way it is.
https://zachholman.com/talk/utc-is-enough-for-everyone-right
Random good example post: https://devblogs.microsoft.com/oldnewthing/20220328-00/?p=10...
To me, it's representative of all the good bits of Microsoft, now, and also in the past. I wish they had more Raymond Chens, and less... whoever it is driving their focus on crappy adware, telemetry, bad "modernized ux", user hostile behaviour in general.
"why's (poignant) Guide to Ruby"
All right, this one is not purely technical. It's technical, but mixed with comics, art and a lot of personality.
It is an old classic in the community, and something that I aim up towards. Opened up my imagination to what a unique thing a technical book can become.
This book was originally published in 1969 and assumes you know nothing about cars or mechanical systems. They do a great job of getting the reader up to speed quickly without moving too fast or leaving out important concepts.
I was introduced to the book by my high school English teacher. He used it as an example of fine technical writing that doesn't feel like technical writing. I enjoyed the chapter he shared with us so much that I bought the book and read the whole thing. It's a great manual!
https://boingboing.net/2020/08/31/getting-started-in-electro...
Clear and concise articles that really dig into some of the hard technical problems with working at scale.
Has honestly made me a much better systems programmer since starting to read them.
Anything by Donald Knuth. He even teaches good writing in Mathematical Writing.
I always thought IBM held a high standard for their writing. So anything from the IBM System/370 Principles of Operation to their IBM Journal of Research and Development would be good.
Lately, I've been reading Algorithms by Dasgupta, et al and those boys can write.
Inside look at modern web browser (https://developer.chrome.com/blog/inside-browser-part1/) - fun illustrations
Nunjucks (https://mozilla.github.io/nunjucks/templating.html) - easy-to-use site nav
Vodafone + Core Web Vitals case study (https://web.dev/vodafone/) - packed with info and no marketing BS (disclosure: I was majorly involved in that content)
Here is another example, the manual for Microsoft Word 1.0 for DOS: http://toastytech.com/manuals/MS%20Word%201.00%20for%20DOS%2...
Every recipe we’ve tried have been great. But the reason I wanted to share it here is how ATK analyses and shares how they decide the best ingredients for different recipes. Gluten is a very important (and more nuanced than I realized) ingredient in traditional cooking and baking. So when you remove it there are a lot of surprising effects. (And some unsurprising ones). So ATK takes you through those nuances.
It’s really fun to learn and I’m not much of a cook myself :)
Also, their 'Analog Dialog' series [0] are quite something.
Edit: HP, too, made some excellent tech notes back in the day.
[0] https://web.ece.ucsb.edu/~ilan/Classes/ECE2A_F2010/Tutorials...
I feel there has been a decline in the quality of tech writing since the internet became popular. Today's books are often extremely verbose while not conveying content well.
[p.s. RIP Pieter -> Read this: https://web.archive.org/web/20090420070511/http://www.digist...]
https://www.amazon.com/Technical-Writing-Principles-Strategi...
Back in the heydays of Ruby on Rails I also found the Net::SSH library by Jamis Buck to be very excellent in terms of documentation.
Eloquentjavascript
Gentoo Handbook + Arch wiki
SICP <3
ESR's blog
The Emlish book is great. https://zaid-ajaj.github.io/the-elmish-book/#/
Domain Modeling Made Functional: Tackle Software Complexity with Domain-Driven Design and F# Book by Scott Wlaschin is amazing. His blog is also fantastic.https://fsharpforfunandprofit.com/
Get Programming with F# A guide for .NET developers by Isaac Abraham is also very good.
Not F# but the best written technical book I've read has to be The Pragmatic Programmer Book by Andy Hunt and Dave Thomas.
An example of making a boring technical topic into an engaging novel is The Goal Novel by Eliyahu M. Goldratt
https://www.goodreads.com/book/show/2700831-framework-design...
It's an entire ray-tracer explained in the literate programming style.
* Introductory Logic and Sets for Computer Scientists.
* Formal Specification: Techniques and Applications.
both by Nimal Nissanke.
The writing is Precise, Succinct, Clear with lots of examples. A wide variety of topics are explained without overwhelming the reader and all within a decent-sized book.
For example, the “HP ProBook 470 G5 Notebook PC: Maintenance and Service Guide” has an excellent reputation.
If your looking for something a bit more interesting, I suggest Mitigating Attacks on Houses of Worship by CISA: https://www.cisa.gov/sites/default/files/publications/Mitiga...
[0] https://www.boost.org/doc/libs/1_79_0/libs/math/doc/html/ind...
https://m-cacm.acm.org/magazines/2018/6/228044-coz/fulltext
Full disclosure: I know both authors well so I’m probably a little biased.
Bas Kast: The Diet Compass: The 12-Step Guide to Science-Based Nutrition for a Healthier and Longer Life
The title sounds clickbaity but the book isn't. Very toned down, unidological description of the curent state of the science in regards to diet and nutrition.
I can't find the text on line any more. Just ads for it as a collectable.
The blog post on go generics seemed to be a very well written piece.
* Gödel, Escher, Bach: an Eternal Golden Braid (GEB)
* Metamagical Themas
* I Am A Strange Loop (IAASL)
GEB and IAASL are thematically similar, and both are worth a read if you're interested in both Gödel's theorems (plus related work eg Church-Turing) and Hofstadter's philosophy of mind. GEB is a lot more creative and fun; IAASL does a better job of communicating the key technical ideas like incompleteness.
Metamagical Themas is a collection of shorter work, generally technical and fun.
Although Hofstadter was the first to come to my mind, these other authors/works also provide fun and/or excellent examples of technical writing:
* Neal Stephenson's "In the Beginning was the Command Line"
* Velleman's "How To Prove It" and "Philosophies of Mathematics"
* Mittelbach & Goosens "The LaTeX Companion"
* Waldrop's "The Dream Machine"
* Nielsen & Chuang's "Quantum Computation & Quantum Information"
* Lakatos's "Proof & Refutations"
* Chambers "What is this thing called science?"
* Doxiadis & Papadimitriou's "Logicomix".
# Example 1: Old HP application notes
Quote: "In a real sense, Hewlett-Packard sold MEASUREMENTS as well as products. According to one marketing professional, when you go to a hardware store to buy a 5mm drill bit, what you really want is a 5mm hole. So, likewise, as HP developed their massive line of innovative measurement instruments, the customers often had to be educated in the newer processes of the new measurement techniques, permitted by the newest product."
I'm too young to have experienced the heyday of HP as a test & measurement company, but they produced spectacularly good material. Many of their application notes introducing the fundamentals of a field such as spectrum analysis, signal analysis, modal testing etc. remain excellent introductions even today, despite being decades old and thus predating my birth. I've thoroughly enjoyed the following ones (amongst others):
[1] AN243 The Fundamentals of Signal Analysis
[2] AN243-3 The Fundamentals of Modal Testing
[3] AN150 Spectrum Analysis Basics (updated version)
# Example 2: LTC application notes, especially by Jim Williams
A big chunk of my electronics knowledge comes from data sheets and application notes. The application notes by Jim Williams (RIP) stand out to me. Jim obviously was very gifted, but always sides with the (probably much less skilled) reader, making complicated material accessible. He always retains a holistic picture, and also addresses many practical aspects one can easily stumble upon. He does it all with a minimum of math, a maximum of intuition, and a great sense of humour.
While there are many dozens of application notes by him, I particularly like the following one:
[4] AN47: High Speed Amplifier Techniques
Links:
[1] https://www.hpmemoryproject.org/an/pdf/an_243.pdf
[2] https://www.hpmemoryproject.org/an/pdf/an_243-3.pdf
[3] https://www.keysight.com/us/en/assets/7018-06714/application...
[4] https://www.analog.com/media/en/technical-documentation/appl...
Emacs and Vim manuals.
Just a (rather petty) example, React documentation is often lauded as very good,and I kinda agree.
But if you visit from a "low" resolution laptop(1366x768) and click in advanced options to the right on this link:
https://reactjs.org/docs/getting-started.html
It turns out you cannot scroll the options easily by using keys or a 2-button mouse because it does not have a scroll bar (why?). You have to use the scroll-wheel(not everybody has it) or drag down the menu in a clunky way, and this is the documentation of a front-end framework.
Another pet-peeve of mine it is what I call the "Netflix effect", the documentation is fine but there is not a clear, straightforward table of contents, and there are lot of internal links in the documentation so you jump from one place to the other but you are not really sure what order you are following or how much ahead or behind you are jumping from your current section. Microsoft .NET documentation is like that.
On the other hand, this is a very good example(except by the annoying Discuss thing)
Everything is laid out in a very straightforward way, at any moment you have a very clear mental model of where you are in the document.
Postgres, Rails and Django are a little less clear in that sense but still extremely well organized.