From:   Jonathan Corbet <corbet@lwn.net>
To:     Thorsten Leemhuis <linux@leemhuis.info>
Cc:     Randy Dunlap <rdunlap@infradead.org>,
        Lukas Bulwahn <lukas.bulwahn@gmail.com>,
        linux-doc@vger.kernel.org, linux-kernel@vger.kernel.org,
        regressions@lists.linux.dev
Subject: Re: [PATCH v3] docs: describe how to quickly build a trimmed kernel
In-Reply-To: <d233a796-1cb8-a9b3-5a50-043dd2f98b3e@leemhuis.info>
References: <1a788a8e7ba8a2063df08668f565efa832016032.1678021408.git.linux@leemhuis.info>
 <87a60frxk0.fsf@meer.lwn.net>
 <d233a796-1cb8-a9b3-5a50-043dd2f98b3e@leemhuis.info>
Date:   Thu, 16 Mar 2023 12:27:56 -0600
Message-ID: <87edpomtzn.fsf@meer.lwn.net>
MIME-Version: 1.0
Content-Type: text/plain
Precedence: bulk

Thorsten Leemhuis <linux@leemhuis.info> writes:

> Documentation/doc-guide/contributing.rst says that "books" are meant to
> "group documentation for specific readers"; creating a new book for
> tutorials would work against that, as readers (users and administrators
> in this case) then would have to consult two books.

The idea behind that guideline is that readers should be able to know
where to look and to not have to dig through a lot of material that was
not intended for them.  Not that, for any given reader, there should be
exactly one book that has everything they might want.

One could also argue, of course, that readers seeking tutorials are a
different group than those seeking reference material.

> And isn't for example Documentation/process/submitting-patches.rst also
> more of a tutorial than reference material (which we also have in the
> form of Documentation/process/development-process.rst)?

It's a pretty clear example of what happens when you try to combine both
types of documentation - you get something that isn't ideal for either
type of reader.  It tries to take people through the process, but it is
also the only reference document we have on how patches should be
submitted. 

> Does that mean
> it should be moved? Into the same book or a separate book, as it has a
> different target audience? I fear that might quickly get confusing for
> readers without any real benefits

No, I wouldn't move it.  We could, someday, consider splitting it into
two more focused documents, one of which could (say) go under tutorials/.

> Or did I understand the idea of a new book wrong and you meant something
> else? Like creating Documentation/admin-guide/tutorials/ and putting the
> text there? That might work and would help future authors to get the
> right mental model when writing new texts. But I'm not sure that's worth it.

I wasn't thinking of doing it that way, but we could certainly consider
it.  It doesn't seem like we would have vast numbers of these, though,
and they would mostly cover relatively elementary topics, so a single,
top-level directory might be better if we decide to take this path.

Thanks,

jon