From owner-svn-doc-all@freebsd.org Thu Oct 1 16:44:20 2015 Return-Path: Delivered-To: svn-doc-all@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 BE278A0DF4D for ; Thu, 1 Oct 2015 16:44:20 +0000 (UTC) (envelope-from bsd-src@helfman.org) Received: from mail-ig0-f178.google.com (mail-ig0-f178.google.com [209.85.213.178]) (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 8EA351217 for ; Thu, 1 Oct 2015 16:44:20 +0000 (UTC) (envelope-from bsd-src@helfman.org) Received: by igbkq10 with SMTP id kq10so22847507igb.0 for ; Thu, 01 Oct 2015 09:44:13 -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=juxrMRWNJtlQ8/vOrtUxsO1l9w0WTclY9/6T2394e4fj8riOrCSmhB4dK0TMaa5y8h l5Pj4aF5H3gySAWpX2eQxAw8OSywAtW4zxtgShNASFdpXWcmTzgs/HB6PFHh/1mliJ2b 3NZxdLzOYgaonyIRbvF6pA036NY9g5SFLJggb7bM+ZRbs0eth55XDK6Z1SADL7WzHg4E q9h9EKVVIuBNB/4w/MZIKSHUp6Gk+aKhTVkQDwfscPHkwjWsHnw9E5Fx0d3x03mzkCJY pVMni9XuiLCYbLmzrrSyIWevVNw5ku6AcJM4VV7QnHPx03tp/L959BYhDUT+o4U+/Skh Tmtg== X-Gm-Message-State: ALoCoQklvc5WJQdQ2GWz7mMpPLcs3qcf5eP+P6/UdAL0bp0iFW68I9sNs0n4HUNc+LJFWMLwwh/1 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-all@freebsd.org X-Mailman-Version: 2.1.20 Precedence: list List-Id: "SVN commit messages for the entire doc trees \(except for " user" , " projects" , and " translations" \)" List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , X-List-Received-Date: Thu, 01 Oct 2015 16:44:20 -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