On Wed, 7 Dec 2016 16:42:58 +0100 Daniel Vetter <daniel.vetter@xxxxxxxx> wrote: > We already had a super-short blurb, but worth extending it I think: > We're still pretty far away from anything like a consensus, but > there's clearly a lot of people who prefer an as-light as possible > approach to converting existing .txt files to .rst. Make sure this is > properly taken into account and clear. > > Motivated by discussions with Peter and Christoph and others. I do think we should put something in to guide people in the right direction. And yes, it should, itself, be light-handed and minimal. [...] > Documentation/kernel-documentation.rst | 28 ++++++++++++++++++++++++++-- > 1 file changed, 26 insertions(+), 2 deletions(-) I do, however, also believe that it should apply to relatively recent docs-next :) > diff --git a/Documentation/kernel-documentation.rst b/Documentation/kernel-documentation.rst > index 0dd17069bc0b..5bffe5a418aa 100644 > --- a/Documentation/kernel-documentation.rst > +++ b/Documentation/kernel-documentation.rst > @@ -77,9 +77,27 @@ Specific guidelines for the kernel documentation > > Here are some specific guidelines for the kernel documentation: > > -* Please don't go overboard with reStructuredText markup. Keep it simple. > +* Please don't go overboard with reStructuredText markup. Keep it simple. A lot > + of core kernel developers prefer plain text, with a big emphasis on plain. In > + the end if we have pretty generated docs which the subject experts don't > + like to edit and keep up-to-date everyone loses. > > -* Please stick to this order of heading adornments: > + Be especially considerate when converting existing documentation. There's a > + wide scale from annotating every little bit with in-line styles to only > + touching up the bare minimum needed to integrate an existing file into the > + larger documentation. Please align with the wishes of the maintainer to make > + sure that documentations stays useful for everyone. I think this is about where I figured out why I'm not 100% ready to jump on this. What we're doing here is mixing two things: information on how to write documents, and information on how to convert existing documents. I'm not really opposed to applying the patch as-is, but I do wonder if what we really need is a new section aimed specifically at people doing conversions? The concerns *are* a bit different, and there's more information we could put into a conversion section that isn't relevant to others. Plus we could remove it some day far in the future when everything's converted :) > +* Don't just blindly convert documents, also carefully review them and fix up > + any issues in the text itself. Updated docs might trick readers into believing > + they're accurately reflecting current best practice, which would be rather > + harmful if the text itself is entirely outdated. > + > +* When converting existing documents, please try to retain the existing heading > + styles as much as possible. Sphinx accept almost anything, as long as it's accept*s* (or "will accept") > + consistent and headings all start in column 1. > + > + For new documents please stick to this order of heading adornments: > > 1. ``=`` with overline for document title:: > > @@ -107,6 +125,12 @@ Here are some specific guidelines for the kernel documentation: > the order as encountered."), having the higher levels the same overall makes > it easier to follow the documents. > > +* For inserting fixed width text blocks (for code examples, use case > + examples, etc.), use ``::`` for anything that doesn't really benefit > + from syntax highlighting, especially short snippets. Use > + ``.. code-block:: <language>`` for longer code blocks that benefit > + from highlighting. > + I think we should add a sentence somewhere saying: Note that, if the sentence before the block ends with ":", you can simply add a second colon rather than putting in a separate "::" line. I've had to tell a few people that. It's a tiny detail, but one that does improve the readability of the resulting documents and reduce the intrusiveness of conversions. Thanks, jon -- To unsubscribe from this list: send the line "unsubscribe linux-doc" in the body of a message to majordomo@xxxxxxxxxxxxxxx More majordomo info at http://vger.kernel.org/majordomo-info.html
