Bug 740598 - Grammar/sentence structure unwieldy and difficult to follow
Summary: Grammar/sentence structure unwieldy and difficult to follow
Keywords:
Status: CLOSED CURRENTRELEASE
Alias: None
Product: Red Hat Enterprise Linux 6
Classification: Red Hat
Component: doc-Resource_Management_Guide
Version: 6.2
Hardware: All
OS: Linux
unspecified
unspecified
Target Milestone: rc
: ---
Assignee: Martin Prpič
QA Contact: ecs-bugs
URL:
Whiteboard:
Depends On:
Blocks:
TreeView+ depends on / blocked
 
Reported: 2011-09-22 15:35 UTC by Kwan Lowe
Modified: 2011-12-07 12:43 UTC (History)
1 user (show)

Fixed In Version:
Doc Type: Bug Fix
Doc Text:
Clone Of:
Environment:
Last Closed: 2011-12-07 12:43:42 UTC


Attachments (Terms of Use)

Description Kwan Lowe 2011-09-22 15:35:50 UTC
Description of problem:
The grammar/sentence structure needs editing. The text has good information, but there are run-on sentences, improper grammar (e.g., sentences end with dangling prepositions, voice switches to imperative and back, etc.). The text could be drastically improved with diagrams.

Version-Release number of selected component (if applicable):


How reproducible:
N/A

Steps to Reproduce:
1.
2.
3.
  
Actual results:
Original:
"Any process (task) on the system which forks itself creates a child process (task). The child task automatically becomes members of all of the cgroups its parent is members of. The child task can then be moved to different cgroups as needed, but initially, it always inherits the cgroups (the "environment" in process terminology) of its parent task.
As a consequence, consider the httpd task that is a member of the cgroup named half_cpu_1gb_max in the cpu_and_mem hierarchy, and a member of the cgroup trans_rate_30 in the net hierarchy. When that httpd process forks itself, its child process automatically becomes a member of the half_cpu_1gb_max cgroup, and the trans_rate_30 cgroup. It inherits the exact same cgroups its parent task belongs to.
From that point forward, the parent and child tasks are completely independent of each other: changing the cgroups that one task belongs to does not affect the other. Neither will changing cgroups of a parent task affect any of its grandchildren in any way. To summarize: any child task always initially inherit memberships to the exact same cgroups as their parent task, but those memberships can be changed or removed later."


Expected results:

Suggestion:
A child task automatically inherits the cgroup membership of its parent but can be moved to different cgroups as needed. Once forked, the parent and child processes are completely independent. 

Additional info:
There is good information in the guide, but it appears to have been written by engineers for engineers. The above is just a single example from the introductory pages, but the rest of the guide has similar issues.

Comment 2 Martin Prpič 2011-11-17 17:39:36 UTC
(In reply to comment #0)

Hi Kwan,

I've added some fancy graphics that (hopefully) make the Rules 1-4 in the introductory chapter a bit more clear. I've fixed some grammar mistakes as well. However, I could argue some of your points, such as sentences ending with dangling prepositions. I don't think that's a grammar mistake. Also, you did not provide any specific examples, and quickly going through the whole guide, I don't see anything majorly wrong grammar or composition. Please do let me know specific points in which the guide lacks quality.

Also, if you are interested, you could join the Fedora docs team and help improve the guide yourself :) Find more info here: https://fedorahosted.org/resource-management-guide/

Nevertheless, thank you for your feedback. Please do share more of your thoughts on this guide if you get the time. It is greatly appreciated.

The changes will be reflected in the 6.2 version of the Resource Management Guide. I am moving this bug to ON_QA for now, but feel free to re-open it after the 6.2 release.

Cheers,
Martin

Comment 5 Martin Prpič 2011-12-07 12:43:42 UTC
6.2 version of the RMG available at:

https://docs.redhat.com/docs/en-US/Red_Hat_Enterprise_Linux/6/html/Resource_Management_Guide/index.html

Closing for now.

Cheers,
Martin


Note You need to log in before you can comment on or make changes to this bug.