On Wed, Feb 9, 2011 at 8:50 AM, Doug Franklin <jehosep...@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. -- Godfrey godfreydigiorgi.posterous.com -- 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.
