Em Wed, 02 Nov 2016 16:05:13 +0000 Luis de Bethencourt <luisbg@xxxxxxxxxxxxxxx> escreveu: > 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. I also wrote a series of articles at: https://blogs.s-osg.org/new-improved-linux-kernel-media-documentation/ I intend to write also some articles there about PDF, with seems really tricky to get it right on Sphinx. > > > 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. > > I'd complement that you should test the output also for PDF... There are some special tags and, sometimes some spells to make it work. > 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 Nothing wrong with the above patch, but, IMHO, it would be better to only fix such typos on files already converted to ReST, as otherwise it could conflict with a patch with someone else would be doing such conversion. Just my 2 cents. In time: I'm not touching at Documentation/usb.tmpl, or on any other DocBook document. > > 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. Markus has a script with helps with such conversion. I guess he actually has conversion for everything, but you'll need to dig into the kernel-doc markups, as some will break after the conversion. > > > > 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 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
