[HN Gopher] Learning technical writing using the engineering met... ___________________________________________________________________ Learning technical writing using the engineering method (2016) [pdf] Author : Tomte Score : 61 points Date : 2020-02-09 19:43 UTC (3 hours ago) (HTM) web link (www.cs.tufts.edu) (TXT) w3m dump (www.cs.tufts.edu) | supernova87a wrote: | 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. ___________________________________________________________________ (page generated 2020-02-09 23:00 UTC)