[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)