Hi Jon, As I wake up too early today, due to the time zone differences, and inspired by your article about documentation at lwn (https://lwn.net/Articles/704613/), I decided to take some time and do some brain storming to help with the KS discussions. Feel free to pick the good things here, and discard the rest ;) This is based on the work I've doing on the past few months with the media conversion, and, mainly my work with regards to development process and admin guides. Btw, I wrote some articles to document the challenges on those two books that might be interesting for the discussions too: https://blogs.s-osg.org/creation-linux-kernel-users-manual/ https://blogs.s-osg.org/documenting-linux-kernel-development-process/ They're part of an attempt from my side As to document the challenges I'm having with the documentation conversion: https://blogs.s-osg.org/new-improved-linux-kernel-media-documentation/ I'm c/c Greg, as I listed several things related to the ABI documentation. ReST conversion - some stats ============================ If I got it right, this is the current status - about 600 files on ReST - 305 ABI files + ABI/README - 32 files with translations to Japanase, Korean and Chinese; - 30 files on DocBook - about 6k plain files to be converted, being 97 files at the Documentation/ root directory (96 after EDAC conversion, with I did already). There's still an elephant at the room: who will do the remaining conversions :) Items requiring some sort of definition ======================================= (probably, we won't have time on KS regular time to discuss all of them) Please notice that this is a brainstorm list, with items I remembered, with no particular order. 1) Rename: Documentation -> doc (or docs)? - Change the location for the translated documents? 2) What to do with the remaining 96 files under Documentation? I tried my best to put the "lose" files at Documentation/ under either admin-guide or process. Yet, I skip several files because I didn't know for sure what to do with them... - There are some stuff there that could probably be discarded (for example: eisa.txt); - There are some stuff there that probably belong to driver-api or to some other subsystem (like, for example video-output.txt, with seems to be some GPU documentation); - There are some stuff there that contains both admin documentation and driver documentation (like, for example ntb.txt, with contains ABI documentation, module parameters, - There are files there with even code examples for userspace tools, like: cpu-load.txt - On most cases, some work is needed for those files that are still there... 3) long-term strategy for 00-INDEX: On converted files, the index will be auto-generated, and the index.rst files will contain the documents. Should we keep maintaining the 00-INDEX files in long term? or should we do something else: move it to /README? remove it? put only directories there? 4) Should we add a generic Sphinx module to run scripts (e. g.) kernel-cmd? - If so, what would be the rules for using it? My suggestion it to block it to run only scripts under an specific directory (like Documentation/sphinx) and selected scripts under ./scripts (like ./get-maintainers and ./kernel-doc). Scripts that will be run should be submitted to kernel-doc ML and acked-by the documentation maintainer or merged via documentation tree. 5) ABI parsing via script; - IMHO, this the onlg viable way of handling it; - Perhaps add part of the contents of ABI/README at the rst file; - ABI format: sort, sub-chapters, etc; - ABI files with a "header" text; - Should ABI be kept under docs, if not converted to ReST? - Should we use a new tag to allow descriptions in ReST format? 6) MAINTAINERS file - Should we add it to process documentation? IMHO, we should, at least a "short" version of it, with the name/location of the modules, the git tree and the ML for submissions. 7) PDF, LaTeX and Math extension Can it be improved? Cheers, Mauro -- To unsubscribe from this list: send the line "unsubscribe linux-doc" in the body of a message to majordomo@xxxxxxxxxxxxxxx More majordomo info at http://vger.kernel.org/majordomo-info.html
