On 6/8/10 9:59 AM, Tim Vandermeersch wrote: > Andrew has raised some important issues with outdated docs etc. I > think we should turn all wiki pages into in-source documentation > (using doxygen for example) that is updated nightly. The current wiki > is just not suited for maintainability IMHO, there is no real overview > of files. We can't grep through it. It can also be a set of test > files, as long as it is easier to maintain. Do we really benefit from > the wiki? I mean: Are there users contributing to the wiki who > wouldn't if we moved it to svn/git.
I've been an advocate of in-line documentation for decades. I've managed a number of groups of programmers over several decades, ranging from small to dozens, working on C, C++, Lisp, Perl, Java, JavaScript, assembly language, even Algol and Pascal. In all that time, I have never once seen a project where out-of-line documentation was kept up to date. On the other hand, the projects I worked on and managed that used in-line documentation almost always kept it up to date. It's just natural. Everyone has good intentions, everyone promises to keep the docs up to date, but it just doesn't happen. I've even had projects where developers weren't allowed to change code until after they'd updated the docs, but it didn't work. I'm with Tim on this one. Craig ------------------------------------------------------------------------------ ThinkGeek and WIRED's GeekDad team up for the Ultimate GeekDad Father's Day Giveaway. ONE MASSIVE PRIZE to the lucky parental unit. See the prize list and enter to win: http://p.sf.net/sfu/thinkgeek-promo _______________________________________________ OpenBabel-Devel mailing list [email protected] https://lists.sourceforge.net/lists/listinfo/openbabel-devel
