Em Wed, 24 Apr 2019 14:51:26 +0300 Mike Rapoport <rppt@xxxxxxxxxxxxx> escreveu: > On Tue, Apr 23, 2019 at 05:26:41PM -0300, Mauro Carvalho Chehab wrote: > > Em Tue, 23 Apr 2019 10:54:15 -0600 > > Jonathan Corbet <corbet@xxxxxxx> escreveu: > > > > > On Tue, 23 Apr 2019 15:52:26 +0100 > > > David Howells <dhowells@xxxxxxxxxx> wrote: > > > > > > Suggestions / patches on how to improve things for *all* users of the > > > docs are certainly welcome! > > > > > > I am, incidentally, toying with the idea of trying to put together a > > > documentation microconf at the Linux Plumbers Conference this year. If > > > anybody out there thinks that's a good idea and would like to > > > participate, please let me know. > > > > If you add a microconf to LPC, I'm in. > > +1 > > > IMO, we made big advances with documentation, but there's a lot more > > to be done. Having a microconf to discuss those things may help us > > to bring new ideas about how to keep improving it. > > The most difficult part, IMHO, is to convince people to document things ;-) As David mentioned, maintainers could enforce merging new APIs only with documentation, with the risk of being unpopular. Well, maintainers are not among the most loved ones anyway ;-) <sarcasm/> My experience enforcing it at media subsystem is that it is not that hard to have developers writing documentation, once it becomes a rule, and the maintainers give the example. The big problem is how to deal with legacy stuff. I had to do that myself for the DVB subsystem, where the documentation were frozen back on 2002 days, while lots of new stuff got added (and, worse than that, with some very obscure ioctls that is used only by a single driver and some that were used only by OOT drivers). It take a few years to put it in sync with the code, but, once the ReST conversion was done, it became easier to do the work. Thanks, Mauro
