On 14.03.23 19:35, Jonathan Corbet wrote: > Thorsten Leemhuis <linux@xxxxxxxxxxxxx> writes: > >> Add a text explaining how to quickly build a kernel, as that's something >> users will often have to do when they want to report an issue or test >> proposed fixes. > > So I think the time has come to apply this. Sounds good. > I did have one final > thought, though... In the v2 discussion, you said: > >> Be warned, if it works I might do the same for "reporting issues". ;) >> But let's first see how this goes (and if we get any feedback to be able >> to tell if this experiment worked). > > This caused me to wonder if we shouldn't create a new book called > "tutorials" for this kind of stuff, with an explicit proviso that a more > web-oriented approach is OK in that section? Tutorial documentation > *is* quite different from reference material, but we've really made no > effort to treat the two differently so far. > > Thoughts? Hmmm. Thinking about this makes sense, as yes, reference material and tutorials are different kind of texts. I'm not against separating, but it currently kinda feels wrong. 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. 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)? 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 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. Ciao, Thorsten
