|
|
|
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.
|
|
|
|
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.
|
|
|
|
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.
|
|
|
|
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.
|
|
|
|
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.
|
|
|
|
Julia Evans' comics, zines and blog posts are absolutely brilliant. Accessible, educational and full of personality. https://jvns.ca/
|
|
|
|
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
|
|
|
|
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.)
|
|
|
|
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/
|
|
|
|
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.
|
|
|
|
|
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.
|
|
|
|
|
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/
|
|
|
|
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/
|
|
|
|
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
|
|
|
|
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
|
|
|
|
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.
|
|
|
|
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?
|
|
|
|
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.
|
|
|
|
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.
|
|
|
|
|
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.
|
|
|
|
"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.
|
|
|
|
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.
|
|
|
|
|
|
|
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.
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
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
|
|
|
|
|
|
The Rust Programming Language (the Rust book).
|
|
|
|
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/
|
|
|
|
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.
|
|
|
|
|
I haven't yet been disappointed in digital ocean articles.
|
|
|
|
|
Not quite software development related but check out the application notes and articles from Jim Williams and Bob Pease.
|
|
|
|
Knuth's Literate programming, or maybe his work in general Eloquentjavascript Gentoo Handbook + Arch wiki SICP <3 ESR's blog
|
|
|
|
|
The Linux programming interface. Emacs and Vim manuals.
|
|
|
|
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...
|
|
|
|
|
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.
|
|
|
