linux-kernel - Re: [PATCH v2 56/79] docs: Documentation/*.txt: rename all ReST files to *.rst

lists.openwall.net		lists / announce owl-users owl-dev john-users john-dev passwdqc-users yescrypt popa3d-users / oss-security kernel-hardening musl sabotage tlsify passwords / crypt-dev xvendor / Bugtraq Full-Disclosure linux-kernel linux-netdev linux-ext4 linux-hardening linux-cve-announce PHC
Open Source and information security mailing list archives

Hash Suite: Windows password security audit tool. GUI, reports in PDF.

[<prev] [next>] [<thread-prev] [day] [month] [year] [list]

Date:   Wed, 24 Apr 2019 09:57:56 -0300
From:   Mauro Carvalho Chehab <mchehab@...radead.org>
To:     Mike Rapoport <rppt@...ux.ibm.com>
Cc:     Jonathan Corbet <corbet@....net>,
        David Howells <dhowells@...hat.com>,
        Mike Snitzer <snitzer@...hat.com>,
        Peter Zijlstra <peterz@...radead.org>,
        Linux Doc Mailing List <linux-doc@...r.kernel.org>,
        linux-kernel@...r.kernel.org, linux-arch@...r.kernel.org
Subject: Re: [PATCH v2 56/79] docs: Documentation/*.txt: rename all ReST
 files to *.rst

Em Wed, 24 Apr 2019 14:51:26 +0300
Mike Rapoport <rppt@...ux.ibm.com> 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@....net> escreveu:
> > 
> > > On Tue, 23 Apr 2019 15:52:26 +0100
> > > David Howells <dhowells@...hat.com> 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