HN Explorer

Ask HN: Examples of good technical writing?

298 points by u385639 ↗ HN
I wonder if HN could share their favorite pieces of technical writing?

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!

144 comments

[ 2.8 ms ] story [ 253 ms ] thread
onychomys
D'arcy Wentworth Thompson wrote what is widely considered to be the most beautiful book in biology, and thankfully he wrote it long enough ago that it's now in the public domain. Every sentence is like a little poem.

https://gutenberg.org/ebooks/55264

KineticLensman
This is an interesting recommendation. I scanned several sections and agree that the writing style is pleasing.

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

tuxie_
> This is an interesting recommendation. I scanned several sections and agree that the writing style is pleasing.

> 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.

andrenotgiant
https://www.prisma.io/dataguide/

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.

open-source-ux
Here's an unusual suggestion...

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:

https://usborne.com/gb/books/computer-and-coding-books

noufalibrahim
I haven't read there but there were a series of "Monster" books which taught various topics (also, IIRC by Usborne). I had the ones on simple home chemistry and a photocopy of the one on BASIC programming. The latter was exceptionally informative for a child. Some things stand out.

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.

ipnon
Concrete Mathematics: A Foundation for Computer Science, by Ronald Graham, Donald Knuth, and Oren Patashnik, is the rare example of a textbook that is entirely useful, enlightening, and hilarious all at once.
debanjan16
I have two questions for people who worked through this book:

1. What was your mathematical knowledge when you read this book?

2. What did you gain from working through this book?

jdminhbg
The docs for re-frame[0], a functional reactive framework for ClojureScript, are really excellent. They do a great job explaining the problem, the rationale for the approach taken, and how to actually use the framework. The library is a gem of of both functionality and documentation.

0: http://day8.github.io/re-frame/re-frame/

GrumpyYoungMan
K&R ("The C Programming Language") still stands out, at least to me, for its clarity and conciseness. I have yet to see a programming language manual that equals it.
noufalibrahim
Seconded. However, I would add that most books which have Brian Kernighan as an author are of comparable quality. I'm yet to find a book that hasn't taught me something useful written by the man. I can quite confidently say that if he wrote a cook book, I'd go and buy it.

Other books by him.

1. The UNIX programming environment

2. The Practice of Programming

3. The Go Programming Language

Beltalowda
The AWK book is also pretty good; I read through it a few months ago, and pretty much all of it still works with a modern AWK (such as GNU AWK).

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.

vram22
Some might not know that the K in AWK stands for Kernighan.

https://en.m.wikipedia.org/wiki/AWK

And Brian Kernighan has done a lot more than what I've read in this thread so far (though I've not read the full thing yet, and of course, it changes over time).

His overall influence on the field of software also extends far beyond his own direct work.

https://en.m.wikipedia.org/wiki/Brian_Kernighan

He is one of my top software gurus, since early in my career, since I worked a lot with Unix, from early on, but not only due to his Unix work and writing. I've used the knowledge and wisdom in some of his books to great advantage, throughout my career, and will be forever thankful to him and the rest of the early as well as later Unix "gang" for that.

bewuethr
Two older ones:

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.

noufalibrahim
I believe TPoP is an updated version of Elements.
donquichotte
Came here wanting to mention The Practice of Programming. It seems to be out of print, but I got my hands onto a copy of it some years ago and really enjoyed the clarity, humility and technical depth (mainly in the later parts) of the piece.

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.

noufalibrahim
I think so too. I remember reading Larry Wall's Perl book. I found it rambling and incoherent. Didn't hold my interest for too long. Kernighan's books are quite different.
ahartmetz
The book is not too different from the language, ahem. OTOH, C is not my favorite language, but the K&R C book is the best technical writing I remember reading.
noufalibrahim
Yup. I described it as "too baroque" to someone. It's conceptually too large.
vram22
You found Larry Wall's Perl book rambling and incoherent? And you a professed book-lover? Are you aware that different book authors have different styles? (Ofc you do.) Or that Perl is a language, a set of creators and authors, and an ecosystem that does not feel the need to toe the line of the conventional, in fact, disregards it in favor of exploring different styles / options / methods? Explain yourself, Sir Noufal, or pistols at dawn in Buckingham Park. Okay, your choice of weapons. I shall come armed with the Camel book, nothing else ;)
psyc
Absolutely this. I don’t know that I’ve ever seen any work of nonfiction that equals it. I had cursory familiarity with C in ‘94. I got this book in ‘97. I don’t even recall learning C because it was as if I just skimmed back and forth through the book a couple of times and presto. I knew C. I did one medium sized project with it, and then I got my first real programming job, writing C code among other things.
AlbertCory
K&R is a book I carried around with me for years & years, until finally I had it memorized.

And, of course, Knuth.

raddan
I’ve read K&R and it failed to resonate with me. The problems have always seemed like the type you’d run into if you were the kind of person writing an operating system… in the 70’s… on a minicomputer.

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.

eveningtree
https://poignant.guide/

"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.

maxique
Julia Evans' comics, zines and blog posts are absolutely brilliant. Accessible, educational and full of personality. https://jvns.ca/
lelandfe
Yes thank you

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

johnchristopher
I haven't yet been disappointed in digital ocean articles.
jl6
https://www.postgresql.org/docs/

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.

trakl
The Linux programming interface.

Emacs and Vim manuals.