* 6. a professional programmer teaches by documentation
Sacha Chua puts it more succinctly:
A professional programmer best teaches by the source. No matter how good your documentation is, there is no substitute for the source code.
Then WTF are manpages for?
Sure, you might find out what the different parameters to memset() are, but wouldn't you rather type "man memset"? Even if you did check strings.h, all you'd find out about the function is:
extern __ptr_t memset __P ((__ptr_t __s, int __c, size_t __n));
Ok, memset() source code isn't usually installed by default on your Linux distro. But for any non-trivial project or application, development will goes fastest when everything is documented.
> If you only have documentation and no source code, you'll waste
much time reverse-engineering the whole thing.
Dunno about you, but I've found the opposite is true. Given a good implementation with documentation, I don't even have to look at the source before using it or working on it. If it's broken, *then* I'll dig into the source files and reverse-engineer it.
A good example of a project with good developer documentation and source: PostgreSQL.
A good example of a project with bad source code: qmail. Thankfully not everyone codes like DJB.
(I'm interested in what others consider good and bad examples).
* 7. a professional programmer teaches face-to-face; we've not found a substitute *
Philg shows his academic slant here. To be fair, he did his share of teaching and evangelization through his and arsdigita's bootcamps.
Note that free/open source programmers have become more efficient in sharing source code. They have mechanisms to impose discipline and meritocracy among them. They have mechanisms to guide their work so that all efforts complement each other while enabling them to innovate. They share code, they delegate the work.
You forgot: They document. If face-to-face or realtime discussions are not possible, good documentation is necessary. Otherwise, I tend to agree with you.
Hmm. The philg article I quoted was about teaching and professionalism. We've drifted into development. Oh well.
BTW, while we're discussing professionalism and documentation, I'd just like to thank Bong Munoz if he's still on the list. Back when I was starting out on a project Bong had worked on (with Doc Mana and some other ex-Pluggers), I found one of his notebooks. I probably learned more from Bong's project notes than from any single CS class in college.
Thanks, Bong.
Brian (who is too often guilty of not following his own documentation rules)
-- Philippine Linux Users' Group (PLUG) Mailing List [EMAIL PROTECTED] (#PLUG @ irc.free.net.ph) Official Website: http://plug.linux.org.ph Searchable Archives: http://marc.free.net.ph . To leave, go to http://lists.q-linux.com/mailman/listinfo/plug . Are you a Linux newbie? To join the newbie list, go to http://lists.q-linux.com/mailman/listinfo/ph-linux-newbie
