[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
Re: [Findutils-patches] Manual Readability Feedback
From: |
Bernhard Voelker |
Subject: |
Re: [Findutils-patches] Manual Readability Feedback |
Date: |
Thu, 12 Jul 2018 01:22:02 +0200 |
User-agent: |
Mozilla/5.0 (X11; Linux x86_64; rv:52.0) Gecko/20100101 Thunderbird/52.9.0 |
On 06/28/2018 07:12 AM, Christopher Leonard wrote:
> I am writing to inform you of my brief feedback regarding the readability of
> your manual. This message does not regard a “bug”; this message is an
> informal suggestion to improve the experience of the human manual-reader.
Thanks for the feedback and the suggestions.
> 4.1 Make the Compiler Find the Bugs(fourth paragraph) there is a typo
> “not-fuly-implemented” should be “not-fully-implemented”, but my
> suggestion is to remove the double negative, and rephrase the
> style-guide positively, for example
> “Only use ‘assert’ to catch fully-implemented features of your code.”
________________________^~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
This sounds odd to me - as non-native English speaker - as well.
What about "Avoid to use 'assert' to mark not-fully-implemented features ...".
> 4.2. Factor Out Repeated Code“To pick a contrived example, perhaps
> it modifies a global variable which it (that [original] code) shouldn’t
> be touching in its new home.” I added the parentheses around “that code”
> and further specified the ambiguous reference.
ok
> 4.5 The File System Is Being Modyified(second paragraph)
> In this section, the form “it is possible...could be” sounded redundant.
> My suggestion: “...it is possible for the directory ‘find’ is
> searching to be concurrently moved elsewhere in the file system,
nice
> and [it is possible that] the directory in which ‘find’ is invoked be deleted
> during the search process.”
I'd like to avoid too many clarifying brackets [...] as this disturbs
the reading as well. I'd leave the latter part as is.
I've wrapped the above into a patch in your name.
Okay?
Thanks & have a nice day,
Berny
0001-doc-improve-readability-of-find-maint.texi.patch
Description: Text Data
- Re: [Findutils-patches] Manual Readability Feedback,
Bernhard Voelker <=