12 ms·

Ask HN: Examples of good technical writing?

• johnchristopher 4y ago
  I haven't yet been disappointed in digital ocean articles.
• ford 4y ago
  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 https://developers.google.com/tech-writing
• purpleno 4y ago
  [dead]
• deleted 4y ago
  [deleted]
• eternalban 4y ago
  https://zguide.zeromq.org/ https://zguide.zeromq.org/ [p.s. RIP Pieter -> Read this: https://web.archive.org/web/20090420070511/http://www.digistan.org/spec:1 https://web.archive.org/web/20090420070511/http://www.digist...]
• evolve2k 4y ago
  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 https://zachholman.com/talk/utc-is-enough-for-everyone-right
• onychomys 4y ago
  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 https://gutenberg.org/ebooks/55264
  • KineticLensman 4y ago
    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_ 4y ago
      > 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 4y ago
  https://www.prisma.io/dataguide/ 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.
  • jmknoll 4y ago
    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-databases-by-states https://www.prisma.io/dataguide/just-for-fun/us-most-popular...
    • iRomain 4y ago
      Microsoft Access! I haven't touched that in years.
• simonw 4y ago
  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 https://github.com/casey/just/blob/master/README.md
• oxff 4y ago
  https://doc.rust-lang.org/std/ https://doc.rust-lang.org/std/
• kaycebasques 4y ago
  Rustlings (https://github.com/rust-lang/rustlings https://github.com/rust-lang/rustlings) - interactivity Inside look at modern web browser (https://developer.chrome.com/blog/inside-browser-part1/ https://developer.chrome.com/blog/inside-browser-part1/) - fun illustrations Nunjucks (https://mozilla.github.io/nunjucks/templating.html https://mozilla.github.io/nunjucks/templating.html) - easy-to-use site nav Vodafone + Core Web Vitals case study (https://web.dev/vodafone/ https://web.dev/vodafone/) - packed with info and no marketing BS (disclosure: I was majorly involved in that content)
• open-source-ux 4y ago
  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 https://usborne.com/gb/books/computer-and-coding-books
  • noufalibrahim 4y ago
    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 4y ago
  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 4y ago
    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?
• SPBS 4y ago
  I look up to https://sqlite.org/lpc2019/doc/trunk/briefing.md https://sqlite.org/lpc2019/doc/trunk/briefing.md (discussed at https://news.ycombinator.com/item?id=25167423 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.
• GrumpyYoungMan 4y ago
  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 4y ago
    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 4y ago
      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 4y ago
        Some might not know that the K in AWK stands for Kernighan. https://en.m.wikipedia.org/wiki/AWK 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 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 4y ago
• jdminhbg 4y ago
  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/ http://day8.github.io/re-frame/re-frame/
• behnamoh 4y ago
  Racket’s documentation is really nice: https://docs.racket-lang.org/ https://docs.racket-lang.org/
• steppi 4y ago
  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/index.html https://www.boost.org/doc/libs/1_79_0/libs/math/doc/html/ind... [1] https://scikit-learn.org/stable/ https://scikit-learn.org/stable/
• layer8 4y ago
  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/turbo_c/Turbo_C_Users_Guide_1987.pdf 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%20Manual.pdf http://toastytech.com/manuals/MS%20Word%201.00%20for%20DOS%2...
• layer8 4y ago
  The Perl man pages are great: https://linux.die.net/man/1/perl https://linux.die.net/man/1/perl
  • throwaway787544 4y ago
    Oh man, totally. Every project should aspire to have as comprehensive and accessible docs. https://perldoc.perl.org/ https://perldoc.perl.org/
• rozenmd 4y ago
  I'm often told my React explainers at https://maxrozen.com/articles https://maxrozen.com/articles are very accessible (particularly for non native English speakers)
• Beltalowda 4y ago
  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/ https://flak.tedunangst.com/
• GartzenDeHaes 4y ago
  Starting Forth, if you like a conversational style. As others have said, K&R C for conciseness. https://www.forth.com/starting-forth/ https://www.forth.com/starting-forth/ (PDF)
  • nn3 4y ago
    Also Thinking Forth http://thinking-forth.sourceforge.net/ http://thinking-forth.sourceforge.net/
• sangpal 4y ago
  I enjoy Unity documentation https://docs.unity.com https://docs.unity.com. It is concise and usually includes helpful diagrams.
  • larmstrong 4y ago
    What do you think about the Relay documentation? https://docs.unity.com/relay https://docs.unity.com/relay
• eveningtree 4y ago
  https://poignant.guide/ 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 4y ago
  Julia Evans' comics, zines and blog posts are absolutely brilliant. Accessible, educational and full of personality. https://jvns.ca/ https://jvns.ca/
  • lelandfe 4y ago
    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
  • simonw 4y ago
    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-/ https://jvns.ca/blog/2022/04/26/new-zine--how-dns-works-/
• jl6 4y ago
  https://www.postgresql.org/docs/ 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 4y ago
  The Linux programming interface. Emacs and Vim manuals.
• hlesesne 4y ago
  CERNs OpenStack documentation is pretty terrific. Wish for profit cloud providers had as good. https://clouddocs.web.cern.ch/ https://clouddocs.web.cern.ch/
• mfrw 4y ago
  https://planetscale.com/blog/generics-can-make-your-go-code-slower https://planetscale.com/blog/generics-can-make-your-go-code-... The blog post on go generics seemed to be a very well written piece.
• gaudat 4y ago
  Not quite software development related but check out the application notes and articles from Jim Williams and Bob Pease.
• tyingq 4y ago
  Sqlite has some good documentation. Their explanation of the file format is a good example: https://www.sqlite.org/fileformat.html 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.
• Epa095 4y ago
  Excotic maybe, but I found adyen's documentation quite good https://docs.adyen.com/ https://docs.adyen.com/
• 532nm 4y ago
  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 https://www.hpmemoryproject.org/an/pdf/an_243.pdf [2] https://www.hpmemoryproject.org/an/pdf/an_243-3.pdf https://www.hpmemoryproject.org/an/pdf/an_243-3.pdf [3] https://www.keysight.com/us/en/assets/7018-06714/application-notes/5952-0292.pdf https://www.keysight.com/us/en/assets/7018-06714/application... [4] https://www.analog.com/media/en/technical-documentation/application-notes/an47fa.pdf https://www.analog.com/media/en/technical-documentation/appl...
• ravish0007 4y ago
  Knuth's Literate programming, or maybe his work in general Eloquentjavascript Gentoo Handbook + Arch wiki SICP <3 ESR's blog
• nobozo 4y ago
  Anything that Ken Shirriff writes (http://www.righto.com/ 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.)
• UmbertoNoEco 4y ago
  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 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/ 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.
• vehemenz 4y ago
  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.
  • acherion 4y ago
    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.
• dieselgate 4y ago
  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
• izhak 4y ago
  All W. Richard Stevens books.
• thangalin 4y ago
  On a related note, Diana Reep's "Technical Writing: Principles, Strategies, and Readings" is outstanding. https://www.amazon.com/Technical-Writing-Principles-Strategies-Readings/dp/0205721508 https://www.amazon.com/Technical-Writing-Principles-Strategi...
• jonahbenton 4y ago
  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.
  • rotifer 4y ago
    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 https://news.ycombinator.com/item?id=23453286 [2] https://www.jvns.ca/ https://www.jvns.ca/
  • john-tells-all 4y ago
    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!
• cehrlich 4y ago
  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.
• kashyapc 4y ago
  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/ 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 https://lwn.net [2] https://lwn.net/Articles/531114/#series_index https://lwn.net/Articles/531114/#series_index [3] https://lwn.net/Kernel/ https://lwn.net/Kernel/ [4] https://lwn.net/Archives/ConferenceByYear/ https://lwn.net/Archives/ConferenceByYear/ [5] https://lwn.net/Articles/lsfmm2022/ https://lwn.net/Articles/lsfmm2022/
• thethimble 4y ago
  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-systems.html https://martin.kleppmann.com/2017/03/15/map-distributed-data...
• wkschwartz 4y ago
  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/0143113453 https://www.amazon.com/Chaos-Making-Science-James-Gleick/dp/... [1]: https://www.amazon.com/Information-History-Theory-Flood/dp/1400096235 https://www.amazon.com/Information-History-Theory-Flood/dp/1... [2]: https://linear.axler.net/ https://linear.axler.net/
  • deleted 4y ago
    [deleted]
  • carb 4y ago
    Thank you for the recommendations! These look wonderful.
• bonobocop 4y ago
  I think some of the best technical writing I've enjoyed is: https://aws.amazon.com/builders-library/ 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.
• tunnuz 4y ago
  The Rust Programming Language (the Rust book).
• throwaway787544 4y ago
  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.
  • theodpHN 4y ago
    Agreed on the For Dummies books - the ones I've seen have all been surprisingly good intros to their subjects. Approachable and informative.
• lb1lf 4y ago
  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/App%20notes/Analog%20Dialog.pdf https://web.ece.ucsb.edu/~ilan/Classes/ECE2A_F2010/Tutorials...
• mikewarot 4y ago
  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.0ReferenceManual1986_11515064/page/n101/mode/2up https://archive.org/details/bitsavers_borlandturVersion3.0Re... 2 - https://artofelectronics.net/ https://artofelectronics.net/
  • weinzierl 4y ago
    The context sensitive help in Turbo Pascal was also awesome.
  • randcraw 4y ago
    Jeff Dunteman's book on Turbo Pascal was the best written book I've read on computing. His other books are likewise outstanding.
• sleepydog 4y ago
  This one covering the discovery of the "dirty pipe" vulnerability: https://dirtypipe.cm4all.com/ https://dirtypipe.cm4all.com/
• Animats 4y ago
  "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.
• c0l0 4y ago
  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 https://www.man7.org/linux/man-pages/man8/hwclock.8.html
• CalChris 4y ago
  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.
• bumbledraven 4y ago
  I always thought TCP/IP Illustrated by W. Richard Stevens was very clearly written. https://en.wikipedia.org/wiki/TCP/IP_Illustrated https://en.wikipedia.org/wiki/TCP/IP_Illustrated
• ImageXav 4y ago
  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.
  • bornfreddy 4y ago
    Also by Charles Petzold: Programming Windows. Not sure how the new editions fare, but the first (second maybe?) was great.
    • rramadass 4y ago
      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.
  • charlieflowers 4y ago
    What’s the george box reference? Sounds interesting.
    • ImageXav 4y ago
      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+Ideas+and+Essays%2C+Revised+Edition-p-9780471727552 https://www.wiley.com/en-gb/Improving+Almost+Anything%3A+Ide...
• pyjarrett 4y ago
  Physically Based Rendering by Matt Pharr, et. al. It's an entire ray-tracer explained in the literate programming style.
• shireboy 4y ago
  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-guidelines https://www.goodreads.com/book/show/2700831-framework-design...
• belfalas 4y ago
  I have always found SQLite to have fantastic documentation. Very clear writing. https://www.sqlite.org/docs.html 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.
• spaetzleesser 4y ago
  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.
• noufalibrahim 4y ago
  One book that I've enjoyed a lot is the Programming Pearls book by Jon Bentley. It's informative, concise and surprisingly light.
  • natch 4y ago
    Two books! With “More Programming Pearls” as the second also from him. Fun books.
• randcraw 4y ago
  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”.
  • wunderlust 4y ago
    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.
  • tptacek 4y ago
    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.
    • statictype 4y ago
      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?
      • tptacek 4y ago
        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.
• sirpilade 4y ago
  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 https://en.wikipedia.org/wiki/Learning_Perl
  • dash2 4y ago
    Programming Perl was also pretty masterly.
• 13415 4y ago
  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.
• wunderlust 4y ago
  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 https://philpapers.org/rec/PITWII
  • midenginedcoupe 4y ago
    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.
    • wunderlust 4y ago
      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.
    • t7893478134 4y ago
      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.
• signaru 4y ago
  Crafting Interpreters by Bob Nystrom.
• Hackbraten 4y ago
  Learning Rust With Entirely Too Many Linked Lists [1]. [1]: https://rust-unofficial.github.io/too-many-lists/ https://rust-unofficial.github.io/too-many-lists/
• wheybags 4y ago
  "The old new thing" blog by Raymond Chen at Microsoft: https://devblogs.microsoft.com/oldnewthing/ https://devblogs.microsoft.com/oldnewthing/ Random good example post: https://devblogs.microsoft.com/oldnewthing/20220328-00/?p=106401 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.
• ternaryoperator 4y ago
  Most anything by Bob Nystrom. Some (all?) of his books are available for free on the Web. I recommend starting with Crafting Interpreters.
  • ahonhn 4y ago
    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.
• endgame 4y ago
  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.
• ChrisMarshallNY 4y ago
  I've always liked Steve McConnell's writing, and Joel Spolsky is excellent.
• lhoff 4y ago
  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.
• candyman 4y ago
  Stripe documentation. Joy of cooking.
• raddan 4y ago
  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 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.
• subsection1h 4y ago
  Apple Style Guide https://help.apple.com/applestyleguide/ https://help.apple.com/applestyleguide/ Google Developer Documentation Style Guide https://developers.google.com/style/ https://developers.google.com/style/ Microsoft Style Guide https://docs.microsoft.com/en-us/style-guide/welcome/ https://docs.microsoft.com/en-us/style-guide/welcome/
• AdieuToLogic 4y ago
  FreeBSD: https://docs.freebsd.org/en/books/handbook/ https://docs.freebsd.org/en/books/handbook/
• TaylorAlexander 4y ago
  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.
• kqr2 4y ago
  Forrest Mims III books on electronics are considered classics in teaching electronics: https://boingboing.net/2020/08/31/getting-started-in-electronics.html https://boingboing.net/2020/08/31/getting-started-in-electro... https://www.forrestmims.com/ https://www.forrestmims.com/
• ddv 4y ago
  https://ciechanow.ski/gps/ https://ciechanow.ski/gps/ https://ciechanow.ski/archives/ https://ciechanow.ski/archives/
  • DangitBobby 4y ago
    Seconded, these are amazing.
• N1H1L 4y ago
  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://www.youtube.com/c/3blue1brown
• phamilton 4y ago
  https://docs.microsoft.com/en-us/azure/architecture/patterns/ 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.
• xahrepap 4y ago
  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 :)
• xupybd 4y ago
  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/#/ 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/ 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
• enasterosophes 4y ago
  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".
• thomasfromcdnjs 4y ago
  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-enterprise-filtering/ https://pencilandpaper.io/articles/ux-pattern-analysis-enter...
• rmckayfleming 4y ago
  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.
• rramadass 4y ago
  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.
• prometheus76 4y ago
  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!
• 8bitsrule 4y ago
  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/ https://www.tinaja.com/
• pyuser583 4y ago
  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/Mitigating%20Attacks%20on%20Houses%20of%20Worship%20Security%20Guide_508.pdf https://www.cisa.gov/sites/default/files/publications/Mitiga...
• nicbou 4y ago
  The NHS website would fit here. Their content is very easy to read, even though it's about various medical topics.