findutils-patches
[Top][All Lists]
Advanced

[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



Attachment: 0001-doc-improve-readability-of-find-maint.texi.patch
Description: Text Data


reply via email to

[Prev in Thread] Current Thread [Next in Thread]