Jim Lawrence
accessd at shaw.ca
Sat Sep 7 22:20:45 CDT 2013
Thanks Tina for your comments. I then reread the post again. Jim ----- Original Message ----- From: "Tina Norris Fields" <tinanfields at torchlake.com> To: "Discussion of Hardware and Software issues" <dba-tech at databaseadvisors.com> Sent: Saturday, September 7, 2013 2:39:11 PM Subject: Re: [dba-Tech] Writing Technical Documentation Jim, Yeah, that was one of the strong points the author was making. Telling someone to read the source code isn't the same as teaching that person how the project works. Interesting post. I very much enjoyed the perspective. TNF Tina Norris Fields tinanfields-at-torchlake-dot-com 231-322-2787 On 9/4/2013 11:17 PM, Jim Lawrence wrote: > 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/. > _______________________________________________ dba-Tech mailing list dba-Tech at databaseadvisors.com http://databaseadvisors.com/mailman/listinfo/dba-tech Website: http://www.databaseadvisors.com