On 02/11/16 10:41, Jani Nikula wrote: > 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. Subscribed for a while. Reading it more close now. > > Read https://lwn.net/Articles/692705/ and > https://lwn.net/Articles/704613/ if you haven't already. > Done. > 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. Great summary of the development process. > > 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. > It is also more rewarding because newcomers get to learn by reading the docs, while also contributing. Win win. > 3) Look at documentation patches on linux-doc, review them, test them, > give feedback. > I sent this yesterday, mind reviewing it? http://www.spinics.net/lists/linux-doc/msg41297.html > 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. > Will wait in case Jon wants to add his opinion on this. > 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. > This is a great point. Greg and others worry about the rising barrier of entry to contribute to the kernel. This would be a great thing to hand out to newcomers. I am personally interested if any seasoned maintainers are reading this. > > HTH, > Jani. > Thank you so much for the thorough list Jani. Much appreciated. Luis -- 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
