[Top][All Lists]

[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]

Manual Readability Feedback

From: Christopher Leonard
Subject: Manual Readability Feedback
Date: Thu, 28 Jun 2018 05:12:32 +0000 (UTC)

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.
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.”
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.
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, and [it is possible that] the directory in which 
‘find’ is invoked be deleted during the search process.”
Thank you for your excellent contribution to society! These suggestions are 
intended to be constructive.

reply via email to

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