From owner-svn-doc-head@freebsd.org Thu Oct 1 16:44:35 2015 Return-Path: Delivered-To: svn-doc-head@mailman.ysv.freebsd.org Received: from mx1.freebsd.org (mx1.freebsd.org [IPv6:2001:1900:2254:206a::19:1]) by mailman.ysv.freebsd.org (Postfix) with ESMTP id A45E7A0DF75 for ; Thu, 1 Oct 2015 16:44:35 +0000 (UTC) (envelope-from bsd-src@helfman.org) Received: from mail-ig0-f176.google.com (mail-ig0-f176.google.com [209.85.213.176]) (using TLSv1.2 with cipher ECDHE-RSA-AES128-GCM-SHA256 (128/128 bits)) (Client CN "smtp.gmail.com", Issuer "Google Internet Authority G2" (verified OK)) by mx1.freebsd.org (Postfix) with ESMTPS id 7A6BB1239 for ; Thu, 1 Oct 2015 16:44:35 +0000 (UTC) (envelope-from bsd-src@helfman.org) Received: by igbni9 with SMTP id ni9so19093947igb.0 for ; Thu, 01 Oct 2015 09:44:29 -0700 (PDT) X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20130820; h=x-gm-message-state:mime-version:sender:in-reply-to:references:date :message-id:subject:from:to:cc:content-type; bh=+qsuDKuGjCX6FScymMwIw34u016v5bdxTfKlrpRJA0Y=; b=IfdZSNonqpZ0oW0WrQ1vngF64OepbDvmkAvKE4CqFKKu2JFhK5GoCCIXeZ/BAv7bpB BCRZkJ3kAy95azYCsQ3DFF9xWRxk7mv/cLQS/cHtJlLaWv3fvzSF4DqZ6dIL0ecHSHVU vjVqEGlYPsImc6ZF0gyTSug/CbMWXdhrkGbo8GJI4SYlw1w2lmbL/ZDk5tVEvThlbGVE /pEm2NLbEMQx6wvJ+CGqcdEkMg+0iSfqFOOnbmfcnNyHp8M32D5gp5NBjdxMj8nkp+jO E0JT+hFWot8A/8pD64niq25t/ihXQl4UXGg/tvibS5WxLY2AJlNbKGyvBNPzGZ2dxfq8 WdiA== X-Gm-Message-State: ALoCoQmO0xatWpVXGJDDvwRbTZp/XDyjADl1lGnWFGS5VTCgQxDtIYHl3zEQW+EJZeabpAFaEUYU MIME-Version: 1.0 X-Received: by 10.50.176.228 with SMTP id cl4mr4547034igc.79.1443717534472; Thu, 01 Oct 2015 09:38:54 -0700 (PDT) Sender: bsd-src@helfman.org Received: by 10.107.56.193 with HTTP; Thu, 1 Oct 2015 09:38:54 -0700 (PDT) In-Reply-To: References: <201510011455.t91EteM1034915@repo.freebsd.org> Date: Thu, 1 Oct 2015 09:38:54 -0700 X-Google-Sender-Auth: CKFG7K4fYld2uDrduwhU5uBmE1w Message-ID: Subject: Re: svn commit: r47469 - head/en_US.ISO8859-1/books/fdp-primer/writing-style From: Jason Helfman To: Warren Block Cc: Jason Helfman , Warren Block , doc-committers@freebsd.org, svn-doc-all@freebsd.org, svn-doc-head@freebsd.org Content-Type: text/plain; charset=UTF-8 X-Content-Filtered-By: Mailman/MimeDel 2.1.20 X-BeenThere: svn-doc-head@freebsd.org X-Mailman-Version: 2.1.20 Precedence: list List-Id: SVN commit messages for the doc tree for head List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , X-List-Received-Date: Thu, 01 Oct 2015 16:44:35 -0000 On Thu, Oct 1, 2015 at 8:39 AM, Warren Block wrote: > On Thu, 1 Oct 2015, Jason Helfman wrote: > > On Thu, Oct 1, 2015 at 7:55 AM, Warren Block wrote: >> Author: wblock >> Date: Thu Oct 1 14:55:39 2015 >> New Revision: 47469 >> URL: https://svnweb.freebsd.org/changeset/doc/47469 >> >> Log: >> Swap two words transposed. >> >> Modified: >> head/en_US.ISO8859-1/books/fdp-primer/writing-style/chapter.xml >> >> Modified: >> head/en_US.ISO8859-1/books/fdp-primer/writing-style/chapter.xml >> >> ============================================================================== >> --- >> head/en_US.ISO8859-1/books/fdp-primer/writing-style/chapter.xml Thu >> Oct 1 14:34:32 2015 (r47468) >> +++ >> head/en_US.ISO8859-1/books/fdp-primer/writing-style/chapter.xml Thu >> Oct 1 14:55:39 2015 (r47469) >> @@ -196,7 +196,7 @@ >> For example, commands: >> >> >> - Wrong: Use the command svn to >> + Wrong: Use the svn command to >> update sources. >> >> >> _______________________________________________ >> svn-doc-all@freebsd.org mailing list >> https://lists.freebsd.org/mailman/listinfo/svn-doc-all >> To unsubscribe, send any mail to " >> svn-doc-all-unsubscribe@freebsd.org" >> >> >> >> Why we are documenting what shouldn't be done? I thought that this was >> discouraged. >> > > It is. This section has been around forever, but a bigger issue is that > this type of redundancy is difficult to explain without showing the wrong > way. Suggestions welcome. In looking at the context of this note, it appears the right language has been used. In the spirit of redundancy, it was noted what you shouldn't do, and what you should do followed by examples of both. I don't see why there should be examples of both, after noting what you shouldn't do already. In respect to what we should do, why not note what we should do, as well, followed by an example of what we should do :) Thanks, Jason -- Jason Helfman | FreeBSD Committer jgh@FreeBSD.org | http://people.freebsd.org/~jgh | The Power to Serve