Re: [PATCH v1] docs: new text on bisecting which also covers bug validation

[Jonathan Corbet <corbet@lwn.net>]

Thorsten Leemhuis <linux@leemhuis.info> writes:

> On 16.02.24 20:41, Petr Tesařík wrote:
>> Is this because you want to keep it readable if the target audience
>> reads the source text of the documentation? Otherwise, the .. include
>> directive does not make a difference after rendering to HTML. AFAIK.
>
> It less that I want that, it's more that I got the impression that both
> Jonathan and most of the kernel development community wants the source
> text to be readable; not totally sure, but I think that's the right
> thing to do, too.

As a general rule, yes.  To harp on this one more time, I do think we
could create sections of the manual (a "tutorials" book, say) with a
different set of priorities.

In the documentation session at the last kernel summit, I got some
pretty clear feedback that plain-text readability could be made
secondary to getting the best rendered output, at least in some cases.
Tutorials seems like a good example of such a case, where we could focus
on good web output without, as you say, creating potential maintenance
troubles going forward.

Thanks,

jon