svn commit: r47469 - head/en_US.ISO8859-1/books/fdp-primer/writing-style

[Jason Helfman]

On Thu, Oct 1, 2015 at 8:39 AM, Warren Block <wblock at wonkity.com> wrote:

> On Thu, 1 Oct 2015, Jason Helfman wrote:
>
> On Thu, Oct 1, 2015 at 7:55 AM, Warren Block <wblock at freebsd.org> 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 @@
>>                 <para>For example, commands:</para>
>>
>>                 <informalexample>
>>       -           <para>Wrong: Use the command <command>svn</command> to
>>       +           <para>Wrong: Use the <command>svn</command> command to
>>                     update sources.</para>
>>                 </informalexample>
>>
>>       _______________________________________________
>>       svn-doc-all at freebsd.org mailing list
>>       https://lists.freebsd.org/mailman/listinfo/svn-doc-all
>>       To unsubscribe, send any mail to "
>> svn-doc-all-unsubscribe at 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 at FreeBSD.org     | http://people.freebsd.org/~jgh  | The Power to Serve