From owner-freebsd-doc@FreeBSD.ORG Fri Oct 14 05:58:39 2011 Return-Path: Delivered-To: freebsd-doc@freebsd.org Received: from mx1.freebsd.org (mx1.freebsd.org [IPv6:2001:4f8:fff6::34]) by hub.freebsd.org (Postfix) with ESMTP id A22611065670 for ; Fri, 14 Oct 2011 05:58:39 +0000 (UTC) (envelope-from yanegomi@gmail.com) Received: from mail-qw0-f54.google.com (mail-qw0-f54.google.com [209.85.216.54]) by mx1.freebsd.org (Postfix) with ESMTP id 590358FC18 for ; Fri, 14 Oct 2011 05:58:39 +0000 (UTC) Received: by qadz30 with SMTP id z30so766239qad.13 for ; Thu, 13 Oct 2011 22:58:38 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gmail.com; s=gamma; h=mime-version:in-reply-to:references:date:message-id:subject:from:to :cc:content-type:content-transfer-encoding; bh=MqbTq3TgAGAnxGGqQ6WreNWSahIQRGgRJEBbbA6VJDQ=; b=a0xdhDEkbvXna24C4EUufnteZACzA0B4V2+ePvon3SLceoAv2pAKhb6xLPqutIXUmQ s+aNXnVJXqJgA7KtzUya9Qn8QxVOl0F07RoJFwXIsAboTcZ5rxM7PhyjglY72v/oc9Ce 5B3p4eDl05tCxyd4f5B+a3VgKdNnS8H0p/aJs= MIME-Version: 1.0 Received: by 10.224.213.2 with SMTP id gu2mr5695786qab.85.1318570031513; Thu, 13 Oct 2011 22:27:11 -0700 (PDT) Received: by 10.224.74.82 with HTTP; Thu, 13 Oct 2011 22:27:11 -0700 (PDT) In-Reply-To: References: <201110121030.p9CAUDxd032245@freefall.freebsd.org> Date: Thu, 13 Oct 2011 22:27:11 -0700 Message-ID: From: Garrett Cooper To: Warren Block Content-Type: text/plain; charset=ISO-8859-1 Content-Transfer-Encoding: quoted-printable Cc: Niclas Zeising , freebsd-doc@freebsd.org Subject: Re: docs/160696: style(9) should be mentioned in the devs' handbook X-BeenThere: freebsd-doc@freebsd.org X-Mailman-Version: 2.1.5 Precedence: list List-Id: Documentation project List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , X-List-Received-Date: Fri, 14 Oct 2011 05:58:39 -0000 On Thu, Oct 13, 2011 at 9:13 PM, Warren Block wrote: > On Fri, 14 Oct 2011, Benjamin Kaduk wrote: > >> The overall paragraph feels a bit odd, though; maybe like it's written i= n >> a more informal style than I would expect? =A0A more standard dry, techn= ical >> writing version might be: >> %%%%%%%%%% >> When working in a large codebase such as the &os; source, it is >> important to adhere to a common coding style. =A0This provides uniformit= y > > =A0 =A0 =A0 =A0 =A0 =A0 =A0 ^^^^^^ > "conform" might be better here. I'm usually not touchy feely about wording like this, but unless the rest of the document is worded in such a standoffish / cold manner, I would just keep things polite and neutral. "Conform" sounds really pushy and "When working in a..." sounds condescending in my opinion. Saying something like "The &os; project has a number of established procedures, one of which is a common coding style." may or may not be better, as it's common practice for projects to have a style document and this is more or less just serving as a pointer to that documentation. Thanks, -Garrett