Jim Lawrence
accessd at shaw.ca
Wed Sep 4 22:17:21 CDT 2013
Hi Arthur: "Read the source code"... If you can read the source code and it makes perfect sense, you don't need docs because you have already fully learned. It is almost like a Catch22 argument. Teaching is a real art. If the programmer designer is really good then the chances are their documentation style skips over much of the details but OTOH, if the documentation is written by a non-programmer, they don't skip over any of the details. In both cases the docs are poor at best. Jim ----- Original Message ----- From: "Arthur Fuller" <fuller.artful at gmail.com> To: "Discussion of Hardware and Software issues" <dba-tech at databaseadvisors.com> Sent: Wednesday, September 4, 2013 12:22:18 PM Subject: [dba-Tech] Writing Technical Documentation Steve Losh has posted a nice article on writing tech-docs for programming languages and libraries. When I think back on some of the lib-docs I wrote, I wish that I had read this back then. See http://stevelosh.com/blog/2013/09/teach-dont-tell/. -- Arthur _______________________________________________ dba-Tech mailing list dba-Tech at databaseadvisors.com http://databaseadvisors.com/mailman/listinfo/dba-tech Website: http://www.databaseadvisors.com