Bug 36102 – Inconsistencies and overlooked edits in the text of Handbook Effort page.

• Product: Websites
• Status: RESOLVED FIXED

[Description Robert G. Waycott 2003-12-18 23:54:40 UTC]

Rather than file multiple bugs, I will delineate my findings here in one bug, grouped together because they are on one single page of the website. As this is my first time, please forgive me if this method is improper.

1. Section 'Introduction,' 3rd sentence: usage is "bugreports"--I suggest this should be 'bug reports,' as this not only seems most proper, but also is congruent with the usage of 'bug reports,' two words, on bugs.gentoo.org.

2. Section 'View the Handbook,' 2nd sent.: usage is "PDF-version"--improper hyphenation; there should, in fact, be no hyphen. PDF-version is not a compound speech form, which it would need to be to justify the hyphen. Since 'PDF' is simply a modifier of 'version,' proper usage should be 'PDF version.' This could have been mere oversight, for later in the document there is a non-hyphenated 'PDF versions' printed. The inconsistency ought to be rectified.

3. Section 'Goal,' 2nd sent.: usage is "one, consistent book"--The comma is superfluous.

4. Section 'Status,' 2nd sent.: usage is "USE-flags"--There is considerable inconsistency throughout the website and documentation regarding the term 'USE flags,' which switches between hyphenated and non-hyphenated forms. There is no clear need for the hyphen, as this is not a compound speech form, thus I suggest 'USE flags,' which seems most proper. However, even if it is preferred [for Gentoo] for hyphenation, the need for consistency is paramount.

5. Section 'FAQ,' Question 2, 3rd sent.: usage is "bugreports"--See comments above.

6. Section 'FAQ,' Question 2, 3rd sent.: usage is "the consistencies etc."--There should be a comma before 'etc.' (of course, not exactly *one* character before...still need the space).

7. Section 'FAQ,' Question 2, 5th sent.: This sentence as a whole is rather convoluted; it could use a more direct statement (to avoid its passive tone), as well as clarifications in word choice. My suggestion:

  "If we created PDFs for every architecture and option, we would have to provide numerous PDFs, in which only a few sections differ."

  This would eliminate the passive tone of the statement "If we would create...," the odd "every architecture, every option" in the middle of the statement, the missing comma after "numerous PDFs," as well as the unnecessary "only a small amount of sections," the latter being a overly verbose way of saying "a few." Most importantly, clarity and professionalism is both preserved in the passage, as well as being just a bit more enhanced.

8. Section 'FAQ,' Question 2, 6th sent.: usage is "Talking about ..."--I believe it is correct to say, "Talk about a waste..."; perhaps there might also be added a period to close the paragraph.

9. Section 'FAQ,' Question 2, 8th sent.: usage is "inform the user with all possible options..." >> 'inform the user of all possible options...'

10. Why use such an obtuse word as 'stadia'? Few persons are likely to quickly grasp the intended meaning, especially where 'stadium' is employed. There are more lucid alternatives.


I will check back here for any comments as often as I can. Feel free to email me, if the need arises.

Cheers,

Robert G. Waycott
[e-mail]

Reproducible: Always
Steps to Reproduce:
1. Visit http://www.gentoo.org/doc/en/handbook/index.html from any browser.
2. Find all sections I mention, with applicable suggested errors.
3. Refresh the page...they are still there (until fixed or negated).

Actual Results:  
The errors I suggest for correction are still there.

Expected Results:  
Not applicable

Not applicable.

[Comment 1 Sven Vermeulen (RETIRED) 2003-12-19 01:15:08 UTC]

Thanks; I've updated the document to reflect your proposed changes. I've substituted the "at different stadia" with "in different places".