Hacker News new | past | comments | ask | show | jobs | submit login
Ask HN: Examples of good technical writing?
298 points by u385639 on June 5, 2022 | hide | past | favorite | 141 comments
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!




James Gleick‘s “Chaos”[0] (history of chaos theory) and “The Information”[1] (history of information theory) are so beautifully and artfully written you might forget they’re technical. As close as (history of) science writing comes to poetry.

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/


Thank you for the recommendations! These look wonderful.


Almost anything written by the inimitable LWN.net[1] — their feature-length articles, technical conference coverage, etc. Something that springs immediately to mind is their 7-part series[2] Linux kernel namespaces from 2013. The full series is linked to at the bottom of part 1:

- 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

[3] https://lwn.net/Kernel/

[4] https://lwn.net/Archives/ConferenceByYear/

[5] https://lwn.net/Articles/lsfmm2022/


Code: The Hidden Language of Computer Hardware and Software by Charles Petzold is an excellent work that very clearly guides the reader through the components and steps that lead to the sophisticated computer systems we have nowadays. Each step is explained with no logical leaps and could be followed by a young child.

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.


Also by Charles Petzold: Programming Windows. Not sure how the new editions fare, but the first (second maybe?) was great.


Good choice. That book is one of the best examples of "Technical Writing" and responsible for educating a whole generation of Programmers.

In fact i would go so far as to say it was directly responsible for the success of Microsoft Windows.


The second edition was recently posted on HN. Preorders open and the book will ship in Aug 2022. https://news.ycombinator.com/item?id=31696901


What’s the george box reference? Sounds interesting.


The book is "Improving almost anything - Ideas and essays" and can be found on Amazon, but I think the Wiley description [0] does it more justice. His writing is accessible and full of witticisms such as "When Murphy speaks, listen" (referring to Murphy or Sod's Law). His works are good building blocks for all kinds of research.

[0]https://www.wiley.com/en-gb/Improving+Almost+Anything%3A+Ide...


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


Yes, these are amazing. I just got a physical copy of her DNS zine and it taught me a whole bunch, despite having more than a decade's experience of mucking around with DNS at this point: https://jvns.ca/blog/2022/04/26/new-zine--how-dns-works-/


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


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.


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


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.


I believe TPoP is an updated version of Elements.


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.


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.


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.


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.


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.


Yup. I described it as "too baroque" to someone. It's conceptually too large.


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 ;)


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.


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.


K&R is a book I carried around with me for years & years, until finally I had it memorized.

And, of course, Knuth.


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.


Replying to say thank for a great share, and also to point out this cool map linked at the end of the guide. https://www.prisma.io/dataguide/just-for-fun/us-most-popular...


Microsoft Access! I haven't touched that in years.


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


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.


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.


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/


Some mention of his works here, but not his name

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.


I'll second Michael Kerrisk. Here's what I had to say about "The Linux Programming Interface" in an earlier post [1]:

    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.
From that same list [1] I'll also highlight Graham Hutton, whose writing I find particularly good and clear. He also has a number of YouTube videos on functional programming and Haskell.

Someone also mentioned Julia Evans [2]. She makes complex topics more approachable.

[1] https://news.ycombinator.com/item?id=23453286

[2] https://www.jvns.ca/


Seconded. I skimmed through the doorstop Linux Programming Interface book, and found it surprisingly easy to read and absorb the information. Very clearly written, with lots of examples and cross-references. Wonderful stuff!


DDIA by Martin Kleppmann is fantastic.

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


I think the Turbo Pascal 3.0 manual[1] was one of the best printed manuals I ever owned. It alone was worth the price of the compiler.

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

2 - https://artofelectronics.net/


Jeff Dunteman's book on Turbo Pascal was the best written book I've read on computing. His other books are likewise outstanding.


The context sensitive help in Turbo Pascal was also awesome.


Apple Style Guide https://help.apple.com/applestyleguide/

Google Developer Documentation Style Guide https://developers.google.com/style/

Microsoft Style Guide https://docs.microsoft.com/en-us/style-guide/welcome/


Anything that Ken Shirriff writes (http://www.righto.com/) is excellent. He's a UC Berkeley EE/CS PhD who likes to restore and reverse engineer interesting hardware. His writing is so clear.

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


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


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


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


Sqlite has some good documentation. Their explanation of the file format is a good example:

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.


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.


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?


Common Lisp the Language: 2nd Edition by Guy Steele. It's a bit hard to come by as a physical copy (I ordered mine from Abe Books), but it's a fantastic example of technical writing in many facets. I pretty much read it cover to cover (skimming over some of the more reference-y material).

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://ciechanow.ski/gps/

https://ciechanow.ski/archives/


Seconded, these are amazing.


I am a fan of PHP's official documentation. It's well organized, terse, and relies heavily on exemplification.

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.


The PHP documentation is excellent. I wish other PHP projects / frameworks like Laravel had clear, concise, down to earth documentation like PHP.net's, and doesn't require me to have a degree in computer science to understand the terminology.


Well, it is a novel rather than what you would typically consider "technical writing", but the book "The Martian" was written by an engineer and is chock full of technical stuff with a very engaging presentation! I don't normally read books, but that one I could not put down and I read the whole thing in a week, which is very fast for me.


I very much enjoyed this comprehensive piece on UTC and handling time in code by Zach Holman

https://zachholman.com/talk/utc-is-enough-for-everyone-right


Anything by Bill Bryson, but especially “At Home” and “One Summer: America, 1927”. Both are brilliant.

“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 could be wrong, but I don’t think Bill Bryson’s work is “technical writing” as commonly understood. Still worth reading, however, I’m sure.


Tracy Kidder is a wonderful writer. If you liked “The Soul of a New Machine” you might also like “House” which is on a totally different subject. Is it technical? Sort of. I think about it every time I work on my own house. It’s my favorite Kidder book, and I LOVED “The Soul of a New Machine.”


Raymond's "Cathedral" post is a contender for one of the most overrated pieces of technical writing. "The parts that are interesting are not new, and the parts that are new aren't good". It's justifiably infamous for the now-discredited "Linus's law", about "many eyes making all bugs shallow", but large parts of it are also shoplifted from Brooks and Pike.

I think it's remembered fondly mostly because it was an effective bit of advocacy written during a time period people view fondly.


I feel like security bugs are in a class of their own and need different ways of thinking about them.

If you leave aside security bugs, is Linus’ law still invalid?

Any reference to any material on this?


https://ai.googleblog.com/2006/06/extra-extra-read-all-about...

But more importantly, it says 'all bugs' not 'all bugs except for these other bugs which would make the whole thing untrue'


It's still not true if you leave security bugs out. It's basically never true except for a thin class of superficial bugs --- the bugs you'd intuitively expect to get diagnosed get diagnosed, but nothing else does.


I always thought TCP/IP Illustrated by W. Richard Stevens was very clearly written. https://en.wikipedia.org/wiki/TCP/IP_Illustrated


"The old new thing" blog by Raymond Chen at Microsoft: https://devblogs.microsoft.com/oldnewthing/

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.


The Django documentation is outstanding. Django was my first time doing web programming, and the docs both got me up and running in no time, and also repeatedly surprised me by having easy to understand answers to whatever obscure thing I wanted to know.


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.


How to Keep Your Volkswagen Alive: A Manual of Step-by-Step Procedures for the Compleat Idiot by John Muir and Tosh Gregg..

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!


I look up to https://sqlite.org/lpc2019/doc/trunk/briefing.md (discussed at https://news.ycombinator.com/item?id=25167423) as an example of how to talk about something very technical with simple bullet points. I barely understand 10% of what is written but it is very easy to scan and read.


Most anything by Bob Nystrom. Some (all?) of his books are available for free on the Web. I recommend starting with Crafting Interpreters.


I have Crafting Interpreters (if only I had some time to get into it) and am currently reading Game Programming patterns. Love his writing style. Also love how the illustrations are done by hand.

fwiw I would recommend all programmers read Game Programming Patterns even if they have no intention to ever write a game.


Forrest Mims III books on electronics are considered classics in teaching electronics:

https://boingboing.net/2020/08/31/getting-started-in-electro...

https://www.forrestmims.com/


Racket’s documentation is really nice:

https://docs.racket-lang.org/


I think some of the best technical writing I've enjoyed is: https://aws.amazon.com/builders-library/

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.


https://docs.microsoft.com/en-us/azure/architecture/patterns... is an absolute gem. Each article balances between theory and examples and ties it to Azure without getting in the way of the underlying concept.


Anything by Rachel Carson.

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.


Rustlings (https://github.com/rust-lang/rustlings) - interactivity

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)


On the meta level, Zissner's "On Writing Well" is excellent. The book is enjoyable to read which proves that he knew what he was writing about, and it makes a very strong case that whenever you're writing, it's worth the effort to do it well.


I recently got my hands on an old Turbo C manual, and I miss that kind of technical documentation that actually explained everything from the ground up. See for example Figure 2.2: A Sample Use of Hot Keys in http://bitsavers.informatik.uni-stuttgart.de/pdf/borland/tur...

Here is another example, the manual for Microsoft Word 1.0 for DOS: http://toastytech.com/manuals/MS%20Word%201.00%20for%20DOS%2...


I don’t have time to expound too much, but I really love America’s Test Kitchen’s two Gluten Free books “The How Can It Be Gluten Free Cookbook” volumes 1 and 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 :)


Lots of old Analog Devices app notes are masterpieces of concise technical writing.

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


Stroustrup's C++ books are great. You can read them like a regular book. Scott Meyer's books read well. Kernighan & Ritchie's C book is very good. Mac OS documentation in the 1990's was excellent.

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.


https://zguide.zeromq.org/

[p.s. RIP Pieter -> Read this: https://web.archive.org/web/20090420070511/http://www.digist...]


I thoroughly enjoyed the README for the just tool the other day - very thorough, answered all of my questions, fun to read: https://github.com/casey/just/blob/master/README.md


Not quite software development related but check out the application notes and articles from Jim Williams and Bob Pease.


On a related note, Diana Reep's "Technical Writing: Principles, Strategies, and Readings" is outstanding.

https://www.amazon.com/Technical-Writing-Principles-Strategi...


I have always found SQLite to have fantastic documentation. Very clear writing. https://www.sqlite.org/docs.html

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.


Knuth's Literate programming, or maybe his work in general

Eloquentjavascript

Gentoo Handbook + Arch wiki

SICP <3

ESR's blog


Learning Perl by Randal Schwartz[1] was the funniest programming book I ever read. I must give credit to this book if I enjoyed so much programming perl

[1] https://en.wikipedia.org/wiki/Learning_Perl


Programming Perl was also pretty masterly.


I've been learning F# and the docs are the best I've read.

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


A bit dated, but .NET Framework Design Guidelines is one that came to mind. I read it ages ago, and its content has since been baked into static analysis tools and ides, but at the time as a younger dev I greatly appreciated the prescriptive simple style. “Do, Don’t, Consider” plain English rules, just enough explanation to help understand the rule, and a simple code example. Maybe I’m just weird, but I often think that this style is a good fit for a number of technical areas. I could see for cooking for example, providing similar might help people unsure about the “rules”.

https://www.goodreads.com/book/show/2700831-framework-design...


All W. Richard Stevens books.


Physically Based Rendering by Matt Pharr, et. al.

It's an entire ray-tracer explained in the literate programming style.


A couple of my favourites are;

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


A lot of technical writing is on obscure, proprietary topics. It’s about making the boring and complex become easily understandable, but not necessarily interesting.

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


Starting Forth, if you like a conversational style. As others have said, K&R C for conciseness.

https://www.forth.com/starting-forth/ (PDF)


Also Thinking Forth http://thinking-forth.sourceforge.net/


This isn't exactly what you're looking for, but I found this course [0] from google useful.

[0] https://developers.google.com/tech-writing


I'm often told my React explainers at https://maxrozen.com/articles are very accessible (particularly for non native English speakers)


It’s a stretch but I’d say a lot of modern analytical philosophy could be considered “technical” in the sense that the convention is to articulate ideas and arguments as clearly and precisely as possible.

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.

[1] https://philpapers.org/rec/PITWII


Flippin' eck, I've just tried reading the opening sentence:

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


Fair enough! I'll admit, there are a number of somewhat unwieldy idioms in philosophy, but I think in a lot of cases they do serve to pick out a distinct notion.

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.


Ah, another victim of the nonsense "rule" against infinitive splitting. It gets somewhat clearer if you rewrite both occurrences of "consciously to think" to "to consciously think".

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


For a start there is an implicit assumption that p does not equal q. If you are going to use variables (instead of 'something' and 'something else') then you should use them precisely.


My example of a modern philosopher who writes wonderfully clearly would be David Lewis.


CERNs OpenStack documentation is pretty terrific. Wish for profit cloud providers had as good.

https://clouddocs.web.cern.ch/


FreeBSD: https://docs.freebsd.org/en/books/handbook/


The Perl man pages are great: https://linux.die.net/man/1/perl


Oh man, totally. Every project should aspire to have as comprehensive and accessible docs. https://perldoc.perl.org/


I'm very fond of the boost math documentation [0]. Also scikit-learn's documentation [1].

[0] https://www.boost.org/doc/libs/1_79_0/libs/math/doc/html/ind...

[1] https://scikit-learn.org/stable/


I always loved the in-depth nature and clear writing style of the man page of the hwclock(8) program distributed with util-linux(-ng), and happily refer to it as an example of great documentation whenever I get a chance to: https://www.man7.org/linux/man-pages/man8/hwclock.8.html


This is my favorite CS paper. The writing is clear (almost “simple”), the idea is brilliant, and the entire thing is beautifully presented.

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.


I recently stumbled upon this. Up there with best technical content I've read, helped align the team immediately -> https://pencilandpaper.io/articles/ux-pattern-analysis-enter...


Not IT related and more scientific then technical but imho it somehow fits your description.

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 always thought Don Lancaster's electronic "cookbook" series were top-notch examples of accessible, educational technical writing. Still kicking at 'Guru's Lair' https://www.tinaja.com/


"The 200 Class Seaplane Tender", by "Shaw" is a famous example of writing clarity. T. E. Lawrence ("Lawrence of Arabia") wrote this, while he was involved in testing a speedboat.

I can't find the text on line any more. Just ads for it as a collectable.


I enjoy Ted Unangst's writings because they're both informative as well as written in a kind of fluent non-forced "fun" style that I enjoy: https://flak.tedunangst.com/


It's not writing per se, but from a presentation of complex, technical material standpoint - I find 3blue1brown unparalleled

https://www.youtube.com/c/3blue1brown


https://planetscale.com/blog/generics-can-make-your-go-code-...

The blog post on go generics seemed to be a very well written piece.


I've always liked Steve McConnell's writing, and Joel Spolsky is excellent.


This may not be what your looking for but I really like CASIO product manuals. They are concise, yet provide all the information needed. You can download them for free for any of their products from their website.


Douglas Hofstadter's work provides several examples.

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


For electronics, my vote goes to various spectacular application notes from the electronics industry that have stood the test of time. In comparison to the usual literature (textbooks, papers, etc.), these are often laser-focused on helping the user, often at a holistic level, including practical issues. This is a rare case where the incentives of the readers and producers are well aligned: In order to sell their products, manufacturers need to teach their prospective customers enough to use their products adequately. If a product is good, but a customer makes (potentially silly) mistakes in using it, both the customer and the manufacturer lose -- which is exactly what application notes are intended to counteract.

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


This one covering the discovery of the "dirty pipe" vulnerability: https://dirtypipe.cm4all.com/


I enjoy Unity documentation https://docs.unity.com. It is concise and usually includes helpful diagrams.


What do you think about the Relay documentation? https://docs.unity.com/relay


Excotic maybe, but I found adyen's documentation quite good https://docs.adyen.com/


I haven't yet been disappointed in digital ocean articles.


This is probably considered more “science writing” than technical writing but I’m a fan of Ed Yong’s work, he’s a columnist for The Atlantic I believe


One book that I've enjoyed a lot is the Programming Pearls book by Jon Bentley. It's informative, concise and surprisingly light.


Two books! With “More Programming Pearls” as the second also from him. Fun books.


The NHS website would fit here. Their content is very easy to read, even though it's about various medical topics.


Crafting Interpreters by Bob Nystrom.


Learning Rust With Entirely Too Many Linked Lists [1].

[1]: https://rust-unofficial.github.io/too-many-lists/


The Rust Programming Language (the Rust book).


Stripe documentation. Joy of cooking.


The Linux programming interface.

Emacs and Vim manuals.


https://doc.rust-lang.org/std/


One often overlooked aspect of technical writing is the formatting/ease of navigation. You could have the most wonderful documentation, very clearly written, but if its navigation is a pain it will degrade the experience and frustrate the user.

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)

https://javascript.info/

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.


La Technique, Jacques Pepin

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.


Agreed on the For Dummies books - the ones I've seen have all been surprisingly good intros to their subjects. Approachable and informative.




Consider applying for YC's Spring batch! Applications are open till Feb 11.

Guidelines | FAQ | Lists | API | Security | Legal | Apply to YC | Contact

Search: