Received-SPF: pass (google.com: domain of linux-kernel+bounces-72046-linux.lists.archive=gmail.com@vger.kernel.org designates 2604:1380:45e3:2400::1 as permitted sender) client-ip=2604:1380:45e3:2400::1;
From: Jonathan Corbet <corbet@lwn.net>
To: Thorsten Leemhuis <linux@leemhuis.info>, Petr =?utf-8?B?VGVzYcWZw61r?=
 <petr@tesarici.cz>
Cc: regressions@lists.linux.dev, linux-doc@vger.kernel.org,
 linux-kernel@vger.kernel.org, Bagas Sanjaya <bagasdotme@gmail.com>, Nathan
 Chancellor <nathan@kernel.org>
Subject: Re: [PATCH v1] docs: new text on bisecting which also covers bug
 validation
In-Reply-To: <62ea7097-256c-4331-b937-778444125a06@leemhuis.info>
References: <bf1d2eba0d291ff583e01b5985a0dec248eaf27a.1708072870.git.linux@leemhuis.info>
 <20240216204140.2ecbceec@meshulam.tesarici.cz>
 <62ea7097-256c-4331-b937-778444125a06@leemhuis.info>
Date: Mon, 19 Feb 2024 15:12:52 -0700
Message-ID: <87a5nwm7bv.fsf@meer.lwn.net>
Precedence: bulk
MIME-Version: 1.0
Content-Type: text/plain; charset=utf-8
Content-Transfer-Encoding: quoted-printable

Thorsten Leemhuis <linux@leemhuis.info> writes:

> On 16.02.24 20:41, Petr Tesa=C5=99=C3=ADk 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