Thorsten Leemhuis <linux@xxxxxxxxxxxxx> 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
