Wed Feb 9 12:23:34 CST 2011 Godfrey DiGiorgi wrote: > On Wed, Feb 9, 2011 at 8:50 AM, Doug Franklin <jehosephat at mindspring.com> > wrote: > >> ... I want to know why or under what circumstances I might wish to use a > >> particular tool or technique. ... > > > > Yep. It's a really common problem with technical documentation. They > > (usually) tell you 'what' and 'how'. Rarely to they give you any idea of > > 'why' and 'when'. > > It's a difficult thing to keep in one's head while writing > documentation for complex technical subjects. We tend to get caught up > in the trees and forget to consider the forest and the landscape in > which it sits ... > > I make a point of actually writing down, for each element of a system > I'm documenting, four basic questions: > > What is this? > Why is it important to know about it? > How and When is it used? > How is it implemented? > > Having those four questions in front of me as I work my way through a > mass of engineering notes, design specs, and bug reporte, many of > which may be way over my head - totally opaque! - at first, keeps me > focused on explaining to an audience what they need to know in > language they can understand.
That's great! That's basically what they say in the books about scientific/engineering writing. The very first thing a writer has to recognize are these three factors: audience, purpose, and occasion. The first, audience, defines "what do they know?", "why are they reading?", "what expectations (and biases?) they have?" The second, purpose, can be "to perform" or "to persuade". The last one, occasion, defines things like format, formality, deadlines, politics, etc. >From these considerations, the questions and the rationale you listed follow. I was teaching this material to physics major senior students just a week ago in my course "The Art of Scientific Communication". If anyone is interested in reading, - I have a list of a few good books that discuss these and related topics in detail in a rather clear language: http://www.worldcat.org/profiles/roshchin/lists/1723072 Igor -- PDML Pentax-Discuss Mail List PDML@pdml.net http://pdml.net/mailman/listinfo/pdml_pdml.net to UNSUBSCRIBE from the PDML, please visit the link directly above and follow the directions.
