On Wed, 02 Nov 2016, Luis de Bethencourt <luisbg@xxxxxxxxxxxxxxx> wrote: > I also offer my help, let me know if you see anything I can do. Luis, Patrice, anyone else out there willing to help: here's a list of stuff to do, off the top of my head. I'm sure Jon will amend this. 0) Some basics first Subscribe to linux-doc. Read it. Read https://lwn.net/Articles/692705/ and https://lwn.net/Articles/704613/ if you haven't already. Figure out how to build the documentation. Read the part about writing kernel documentation. Also at http://static.lwn.net/kerneldoc/kernel-documentation.html. For most things under Documentation, you'll want to use the docs-next branch of git://git.lwn.net/linux.git. That has the latest stuff. If you use Linus' master, you'll be working on old stuff. For fixing kernel-doc source code comments, you'll need to use the appropriate subsystem tree, see MAINTAINERS. In any case, most changes need to be sent to both linux-doc and the relevant subsystem/driver mailing list. See MAINTAINERS and scripts/get_maintainer.pl. Whatever you do, don't spend forever polishing it privately. Otherwise someone might beat you to it, and effort will be wasted. Read the list, maybe someone's already posted patches that just haven't been merged yet. 1) Build documentation. Look at errors during build, fix them. Some of the issues come from source code comments via the kernel-doc extension; those changes need to go through the appropriate subsystem, not via the documentation tree. Watch out, some of the things may have been fixed in the subsystem repo already. 2) Build documentation. Read the output, fix issues, improve the language, improve the presentation. Ditto about source code comments. Personally, I think this is both very important and unfortunately laborous, because this is mostly stuff that Sphinx won't warn about. 3) Look at documentation patches on linux-doc, review them, test them, give feedback. 4) Convert DocBook templates under Documentation/DocBook to Sphinx. The conversion is actually the easy part; figuring out whether the documentation is still relevant and where to stick it in the Sphinx build is harder. Jon may have some vision on this, but personally I'd like to obliterate DocBook first, and then figure out what to do with the resulting converted rst documents. 5) Convert .txt files under Documentation to .rst. There are caveats here. Not everything needs to be converted. Some of the stuff is obsolete, and converting might be wasted effort. Just converting without updating to reflect current kernels is hazardous, because the obsolete information will then be more accessible with the converted documentation on the web. People like plain text, don't go overboard with rst markup. Use discretion. For both 4) and 5) I'd really like the seasoned kernel devs to actively hand out stuff to willing new hands. HTH, Jani. -- Jani Nikula, Intel Open Source Technology Center -- 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
