[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.
[Prev in Thread] |
Current Thread |
[Next in Thread] |
- Manual Readability Feedback,
Christopher Leonard <=