On Wed, 26 Sep 2018 12:34:14 -0700 "Darrick J. Wong" <darrick.wong@xxxxxxxxxx> wrote: > This series converts the existing in-kernel xfs documentation to rst > format, links it in with the rest of the kernel's rst documetation, and > then begins pulling in the contents of the Data Structures & Algorithms > book from the xfs-documentation git tree. No changes are made to the > text during the import process except to fix things that the conversion > process (asciidoctor + pandoc) didn't do correctly. The goal of this > series is to tie together the XFS code with the on-disk format > documentation for the features supported by the code. Some overall comments: - I certainly approve of improving the documentation and bringing it into the docs tree - even if you don't CC the docs maintainer :) - When people do this work, I often end up asking them to think about who the audience is for the documentation. Developers tend to want to group all of their docs together, but readers - the people the docs are for - tend to have different ideas. So, for example, the xfs.txt document converted in part 1 really, IMO, belongs in the admin guide - it's information for system administrators. The data structures and algorithms stuff, instead, is aimed at developers. I would really argue for separating the two. It's more work, but it's friendlier to our readers in the long term, and moves us away from our current pile of unorganized text. - CC-SA is a great license for documentation; I would rather use it for all kernel docs. But I think we head into dangerous territory if we introduce non-GPL-compatible licenses into the kernel documentation. The docs pull a lot of text from the code itself, to the point that it's really hard to say that the processed docs are not a derived product of the kernel code itself. Do we really want to create a situation where the output of "make *docs" can't be legally distributed? Hmm...it looks like we have exactly one document asserting CC-SA now, slipped in by Willy for 4.16. If I'd noticed it, I would have complained at the time; maybe I'll do so now. In any case, I think we need to be careful about adding more. Thanks, jon
