[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/.
>