On 21 Aug 2010, at 22:15, Doug Barton wrote: > On Sat, 21 Aug 2010, Rui Paulo wrote: > >> On 21 Aug 2010, at 19:20, Doug Barton wrote: >> >>> On 08/21/2010 05:07, Rui Paulo wrote: >>>>> Meanwhile, the fact that in the past code has been committed >>>>> without man pages is the exact cause of the problem you're >>>>> describing. It is certainly not a justification for continuing to >>>>> do it wrong. >>>> >>>> Reverting code just because it doesn't have a man page is pointless. >>>> Everyone can write the damn man page, but not everyone can write >>>> code. You should really take this into consideration when proposing a >>>> commit to be reverted. >>> >>> So let's assume that having lots of code in the tree without a man page is >>> a problem. Further, let's assume that we don't want the problem to get >>> worse. How do you propose that we accomplish that? >> >> By writing man pages...? > > But that's the status quo (I.e., hope that people will/eventually write man > pages for stuff) and it hasn't worked so far. The situation isn't actually > going to be improved until we make a change. A simple (and I think abundantly > reasonable) change that we can make today is, "Don't allow new work to be > committed without a man page." > > Meanwhile, there are a lot of benefits to this idea above and beyond the > obvious one of having man pages for stuff. The biggest single benefit is that > actually writing documentation for things forces you to re-examine > assumptions, work through non-obvious and/or non-default code paths, etc. > Speaking for myself, it's happened on more than one occasion that as I sit > down to document some piece of code I realize that there are either bugs, or > at least a better way of doing something. Requiring developers to work > through this process before code goes into the tree gets us better code in > addition to documentation.
If your concern is to change the status quo, you do understand that you picked the worst possible thread to hijack ? Esp. since the author promised to roll out a man page. Regards, -- Rui Paulo _______________________________________________ svn-src-all@freebsd.org mailing list http://lists.freebsd.org/mailman/listinfo/svn-src-all To unsubscribe, send any mail to "svn-src-all-unsubscr...@freebsd.org"
