Learning technical writing using the engineering method (2016) [pdf] | Hacker News Reader

Learning technical writing using the engineering method (2016) [pdf]

cs.tufts.edu

217 pointsTomte7 comments

I will say that even if you don't read the bulk of this link, the PDF document itself is a very visually pleasing layout, and the author clearly knows how to design, vary, and break up text to make it more interesting. It's worth a look just to see it briefly.

I will just add that I can recognize good technical writing in 3 stages of sophistication:

Stage 1) Someone who has barely mastered the topic and is at the most basic level just telling you the steps to reproduce the result or operate the items or workflow. Once you learn from the material presented (unless extremely complex or required to keep as reference), you rarely go back and study and appreciate this kind of writing repeatedly.

Stage 2) Someone who has done the analysis and exercise enough that the writing evolves into not just instructions or rote description, but narration through the reasons why they did it this way, the pitfalls to watch out for, what not to do. Starts you thinking about what to do next.

Stage 3) Someone whose telling of the technical detail is so fluid and practiced that the basics are unquestioned -- the writing now includes well-informed opinions and jokes about past attempts at the outcome, why they failed and their historical context in technical terms. Gives advice on the difficulties that will be encountered and the limits of the method. The writing is so informative that you may return to read it again and again throughout your career.

One of my favorite texts that reaches Stage 3 is Numerical Recipes in C (which unfortunately I don't have much occasion to refer to nowadays), and the way that programming philosophy, advice, and technical instruction combines in that work is very impressive. Also, many of Griffiths' physics texts, who manages to write with both technical and conversational/narrative mastery.

If only more writers could be like this.

Those are very interesting points. As someone who wants to improve his technical writing skills, your comment is food for thought. Technical writing seems easy in principle but it is not, of course. Sturgeon's law applies here, even for the most acclaimed and popular documentation and books.

Well said, and, “Stage 3“ in which fluency brings humor to a hard topic, immediately suggests to mind Steven S. Skiena’s The Algorithm Design Manual http://www.algorist.com/

This looks quite interesting, thanks for sharing.

I found the other recent thread on technical writing useful, too: Four kinds of documentation https://news.ycombinator.com/item?id=21289832

How does one get technical writing work? I enjoy writing and wish to do more of it, preferably for money.

Looks a bit like a LaTex output?

Yeah, this is a nice LaTeX document. The learning curve is pretty steep at first, but Overleaf.com has made that easier, and it's well worth learning if you're a writer of any kind.

Reply on news.ycombinator.com