I haven't yet been disappointed in digital ocean articles.
Ask HN: Examples of good technical writing?
31–40 of 145 posts
Re: Ask HN: Examples of good technical writing?
#32K&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
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.
Re: Ask HN: Examples of good technical writing?
#33https://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.
Re: Ask HN: Examples of good technical writing?
#34The Linux programming interface.
Emacs and Vim manuals.
Re: Ask HN: Examples of good technical writing?
#35CERNs OpenStack documentation is pretty terrific. Wish for profit cloud providers had as good.
Re: Ask HN: Examples of good technical writing?
#36https://planetscale.com/blog/generics-can-make-your-go-code-...
The blog post on go generics seemed to be a very well written piece.
Re: Ask HN: Examples of good technical writing?
#37Not quite software development related but check out the application notes and articles from Jim Williams and Bob Pease.
Re: Ask HN: Examples of good technical writing?
#38Sqlite 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.
Re: Ask HN: Examples of good technical writing?
#39Excotic maybe, but I found adyen's documentation quite good https://docs.adyen.com/
Re: Ask HN: Examples of good technical writing?
#40For 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...