Catchup

It seems I was remiss in my blogging.  I completely forgot to blog about TOS chapter 8.  Chapter 8 is titled Explaining the Code, but it's really about documentation; I suppose the two aren't mutually exclusive.  The text describes two types of documentation: ad hoc and planned. 

Basically ad hoc documentation occurs during the working process.  Any code that gets developed must have documentation that explains the reasoning and any unclear code.  We've learned good practices to use to develop sufficient ad hoc documentation in every programming class we've taken.

Planned documentation is the development of a formal document that fully explains a piece of software.  This type of document is of much higher quality than the ad hoc documentation.  We learned how to generate these kinds of documents in Software Architecture and Design.

An important concept the chapter addresses is the waterfall method approach to technical writing.  It outlines

 

1. Planning -- who is the audience? What are the book's goals?

2. Content -- what are the chapters about? Where will you get the information?

3. Writing -- first draft, review, second draft ...

4. Internationalization/Localization -- will the book be translated? Into what languages?

5. Review -- what worked? What didn't? How will the book be maintained? 

 

and says that starting with the first and proceeding down is the best approach.