On Wed, Jan 22, 2020 at 03:54:18PM -0800, Randy Dunlap wrote: > On 1/22/20 3:53 PM, Matthew Wilcox wrote: > > On Wed, Jan 22, 2020 at 04:20:30PM -0700, Jonathan Corbet wrote: > >> This is mostly a collection of thoughts for how people who want to help out > >> can make the docs better. Hopefully the world will respond with a flurry > >> of useful patches. > > > > Thanks for writing this with your characteristic blend of self-deprecating > > humour and supportive advice. One thing which I feel should be mentioned > > is the hard work put in by hundreds of kernel maintainers who have > > written kernel-doc and nobody has done the trivial work to actually > > include those source files in an rst file, so all that documentation > > is being ignored. A great task that's a step up from "fixing typos" is > > "find documentation that's not currently in a kernel book and add it". > > Even if it's just dumped into a "misc" section, having (eg) kvmalloc() > > documentation in a kernel book is a benefit. > > > >> +Please note that some things are *not* typos and should not be "fixed": > >> + > >> + - Both American and British English spellings are allowed within the > >> + kernel documentation. There is no need to fix one by replacing it with > >> + the other. > >> + > >> + - The question of whether a period should be followed by one or two spaces > >> + is not to be debated in the context of kernel documentation. > > > > Do you want to preemptively mention the Oxford comma here? > > > > to allow it, like one or two spaces after a '.'? To not nit-pick over it; use it or not at your preference.
