Skip site navigation (1)Skip section navigation (2)
Date:      Sat, 21 Aug 2010 22:48:46 +0100
From:      Rui Paulo <rpaulo@FreeBSD.org>
To:        Doug Barton <dougb@FreeBSD.org>
Cc:        svn-src-head@FreeBSD.org, Ana Kukec <anchie@FreeBSD.org>, svn-src-all@FreeBSD.org, "Bjoern A. Zeeb" <bz@FreeBSD.org>, src-committers@FreeBSD.org
Subject:   Re: svn commit: r211501 - in head/sys: modules modules/send netinet netinet6 sys
Message-ID:  <26CBB559-FA72-4688-92E9-ED9CEA151B2C@FreeBSD.org>
In-Reply-To: <alpine.BSF.2.00.1008211409420.1942@qbhto.arg>
References:  <201008191131.o7JBV4Yf002412@svn.freebsd.org> <4C6D18BE.2000905@fer.hr> <4C6D95A8.9070105@FreeBSD.org> <20100819213159.B48418@maildrop.int.zabbadoz.net> <4C6DDB74.3090102@FreeBSD.org> <7186318F-0921-41E5-9641-3D6B45E0623B@FreeBSD.org> <4C701901.8030505@FreeBSD.org> <BA312DC6-878D-440F-95C6-4E8F50F75802@FreeBSD.org> <alpine.BSF.2.00.1008211409420.1942@qbhto.arg>

next in thread | previous in thread | raw e-mail | index | archive | help

On 21 Aug 2010, at 22:15, Doug Barton wrote:

> On Sat, 21 Aug 2010, Rui Paulo wrote:
>=20
>> On 21 Aug 2010, at 19:20, Doug Barton wrote:
>>=20
>>> 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.
>>>>=20
>>>> 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.
>>>=20
>>> 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?
>>=20
>> By writing man pages...?
>=20
> 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."
>=20
> 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





Want to link to this message? Use this URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?26CBB559-FA72-4688-92E9-ED9CEA151B2C>