More of Pat's comments addressed in HOWTO file.

1 files changed, 27 insertions, 19 deletions

diff --git a/HOWTO b/HOWTO
index b24ea4a958c1a..012475f5c941f 100644
--- a/HOWTO
+++ b/HOWTO
@@ -72,18 +72,22 @@ Here is a list of files that are in the kernel source tree that are
 required reading:
   Documetation/CodingStyle
     This describes the Linux kernel coding style, and some of the
-    rationale behind it.  The main point here is that we have a coding
-    style, and you cannot ignore it.
+    rationale behind it. All new code is expected to follow the
+    guidelines in this document. Most maintainers will only accept
+    patches if these rules are followed, and many people will only
+    review code if it is in the proper style.
 
   Documentation/SubmittingPatches
   Documentation/SubmittingDrivers
-    These files describe in explicit detail, the proper format of how
-    you need to create your change, what needs to be in your email, what
-    kind of email you should send, who to send it to, and everything
-    else you will need to learn in order to submit a change that will be
-    accepted into the main kernel source tree.  If you do not follow
-    these rules, the odds of your patch being accepted are very low.
-
+    These files describe in explicit detail how to successfully create
+    and send a patch, including (but not limited to):
+       - Email contents
+       - Email format
+       - Who to send it to
+    Following these rules will not guarantee success (as all patches are
+    subject to scrutiny of content and style), but not following them
+    will almost always prevent it.
+ 
     Other excellent descriptions of how to create patches properly are:
 	"The Perfect Patch"
 		http://www.zip.com.au/~akpm/linux/patches/stuff/tpp.txt
@@ -91,12 +95,15 @@ required reading:
 		http://linux.yyz.us/patch-format.html
 
   Documentation/stable_api_nonsense.txt
-    This file describes the rationale behind why the Linux kernel does
-    not have a stable in-kernel API.  If you want to try to come up with
-    a shim-layer for some subsystem, in order to make it easier to adapt
-    your existing code to Linux, or to try to mitigate the rapid change
-    within the Linux kernel source tree, this document describes why
-    such a proposal will fail.
+    This file describes the rationale behind the conscious decision to
+    not have a stable API within the kernel, including for things like:
+      - Subsystem shim-layers (for compatibility?)
+      - Driver portability between Operating Systems.
+      - Mitigating rapid change within the kernel source tree (or
+	preventing rapid change)
+    This document is crucial for understand the Linux development
+    philosophy and is very important for people moving to Linux from
+    development on other Operating Systems.
 
   Documentation/SecurityBugs
     If you feel you have found a security problem in the Linux kernel,
@@ -104,10 +111,11 @@ required reading:
     developers, and help solve the issue.
 
   Documentation/ManagementStyle
-    This document describes how the Linux kernel maintainers work.  If
-    you are ever confused as to exactly why a maintainer is not doing
-    what you want them to, refer to this document to help understand how
-    they work, and how to make their lives easier.
+    This document describes how Linux kernel maintainers operate and the
+    shared ethos behind their methodologies.  This is important reading
+    for anyone new to kernel development (or anyone simply curious about
+    it), as it resolves a lot of common misconceptions and confusion
+    about the unique behavior of kernel maintainers.
 
   Documentation/stable_kernel_rules.txt
     This file describes the rules on how the stable kernel releases