Re: "staging" area for unsorted random files under Documentation/*.rst

[Mauro Carvalho Chehab <mchehab+huawei@kernel.org>]

Em Wed, 19 Feb 2020 02:29:51 -0700
Jonathan Corbet <corbet@lwn.net> escreveu:

> On Tue, 18 Feb 2020 14:26:14 +0200
> Jani Nikula <jani.nikula@linux.intel.com> wrote:
> 
> > On Tue, 18 Feb 2020, Mauro Carvalho Chehab <mchehab+huawei@kernel.org> wrote:  
> > > Shifting those around is not easy (I tried a few times), as some discussions
> > > are required in order to get them at their rightful places.
> > >
> > > So, my current proposal is to just rename them to *.rst, keeping them
> > > where they are, and adding them into an "staging" area at the main
> > > index.rst. See the enclosed patch.    
> > 
> > The obligatory bikeshedding comment, how about adding an actual
> > "staging" directory under Documentation, perhaps with an index.rst of
> > its own?  
> 
> I kind of agree, actually.  If we absolutely must create a trashpile of
> random documents, the top-level directory seems like the worst place for
> it.  Let's hide our shame rather than rubbing everybody's nose in it.

Ok. I'll prepare a patch creating a Documentation/staging and move those
unsorted stuff into it.

I may try to do another attempt to move at least some of those unsorted
documents to a better place before the final one that will place the
remaining ones under staging/.

> > Personally I don't really mind having .txt files around either, just
> > *not* at the top level Documentation directory.  
> 
> In general, RST conversion is not my highest priority at this point.

Well, right now on my TODO list there are just ~20 files left to convert.

I'm excluding from my TODO a few exceptions like config files with .txt 
extensions and translations, plus a couple of text files whose previous
conversion attempts generated heated discussions.

> There is only so much value in creating a more nicely formatted version
> of an unorganized heap of obsolete documentation.  Hopefully we get get a
> bit more focus on quality once this is all behind us...

Yeah, there's little value nicely formatting outdated stuff. However, 
having them converted make those docs more visible, which in turn helps 
to attract devels to send patches updating them.

The more important is that, once we get past this step, we can have a
clearer view about what's left undocumented.

Cheers,
Mauro