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.
Ask HN: Examples of good technical writing?
11–20 of 145 posts
Re: Ask HN: Examples of good technical writing?
#12The 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.
Re: Ask HN: Examples of good technical writing?
#13K&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.
Re: Ask HN: Examples of good technical writing?
#14Racket’s documentation is really nice:
Re: Ask HN: Examples of good technical writing?
#15I'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...
Re: Ask HN: Examples of good technical writing?
#16I 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...
Re: Ask HN: Examples of good technical writing?
#17K&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
Re: Ask HN: Examples of good technical writing?
#18K&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.
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.
Re: Ask HN: Examples of good technical writing?
#19D'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
Re: Ask HN: Examples of good technical writing?
#20Here'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 fo…
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.