Re: Documentation - how to apply patches for various trees

[Linus Torvalds <torvalds@osdl.org>]

On Wed, 3 Aug 2005, Jesper Juhl wrote:
>
> Here's an updated version of my document that attempts to give a short 
> explanation of the various kernel trees and how to apply their patches.
> It incorporates all the feedback I've gotten (thanks guys). 

Can we have more whitespace?

You either have very long paragraphs, or no whitespace between them: I 
can't quite decide which one.

So leave an empty line between paragraphs (and if you already do, you need 
to split them ;) because it's very tiring to not have a nice break every 
once in the flow of text. 

Long paragraphs may be acceptable in fictional literary work that you read
without thinking about what you're reading. There you get into the "flow"  
of the text, and you hopefully don't need to have very many visual breaks
to keep as acnhor-points. However, the same is certainly not true in
technical text, especially something like this where you're trying to
explain somethign that the recipient doesn't ncessarily know.

My rule of thumb is that if you don't have a new paragraph roughly every
five or six lines, it's likely problematic. Maybe I have a shorter
attention span than most, but I don't think so - I just find it much
easier to read text that is nicely broken up, and when it's a "pure ASCII"
medium the only break that works well is an empty line (possibly with
indentation for further visual help - although in this context indentation
tends to be used for a separate issue: examples etc, and is not good for
paragraphs).

And since we have a single empty line implying paragraph breaks, feel free 
to use multiple empty lines to imply "bigger" breaks (you seem to do this 
already).

This email was written with an average paragraph length of 4 lines.

				Linus
-
To unsubscribe from this list: send the line "unsubscribe linux-kernel" in
the body of a message to majordomo@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html
Please read the FAQ at  http://www.tux.org/lkml/