Re: [PATCH 0/1] Start conversion of PowerPC docs

[Jonathan Corbet]

On Fri, 08 Feb 2019 14:40:28 +1100
Michael Ellerman <mpe@xxxxxxxxxxxxxx> wrote:

> > - I don't think this should be a top-level directory full of docs; the top
> >   level is already rather overpopulated.  At worst, we should create an
> >   arch/ directory for architecture-specific docs.  
> 
> We currently have arch specific directories for arm, arm64, ia64, m68k,
> nios2, openrisc, parisc, powerpc, s390, sh, sparc, x86, xtensa.
> 
> Do you mean they should all be moved to Documentation/arch ?

Over time I'm really trying to bring some organization to Documentation/,
and to have that reflected in an RST tree that looks like somebody actually
thought about it.  So yes, I would eventually like to see something like
Documentation/arch, just like we have arch/ in the top-level directory.

> >   I kind of think that
> >   this should be thought through a bit more, though, with an eye toward
> >   who the audience is.  Some of it is clearly developer documentation, and
> >   some of it is aimed at admins; ptrace.rst is user-space API stuff.
> >   Nobody ever welcomes me saying this, but we should really split things
> >   into the appropriate manuals according to audience.  
> 
> I don't think any of it's aimed at admins, but I haven't read every
> word. I see it as aimed at kernel devs or people writing directly to the
> kernel API, eg. gdb developers reading ptrace.rst.
> 
> If Documentation/ wants to be more user focused and nicely curated
> perhaps we need arch/foo/docs/ for these developer centric docs?

Stuff for GDB developers is best placed in the userspace-api docbook; we're
trying to concentrate that there.  Stuff for kernel developers is a bit
more diffuse still; arch/foo/docs may end up being the best place for it in
the end, yes.

> > - It would be good to know how much of this stuff is still relevant.
> >   bootwrapper.txt hasn't been modified since it was added in 2008.  
> 
> It hasn't been modified but AFAIK it's still pretty much accurate and
> definitely something we want to have documented.

That's fine for this (and all the others); I'm just hoping that somebody
has thought about it.  We're carrying a *lot* of dusty old stuff that, IMO,
can only serve to confuse those who read it.  If these files don't fall
into that category, that's great.

> We support some hardware that is ~25 years old, so we have some old
> documentation too, and I'd rather we didn't drop things just because
> they're old.

I agree, as long as they remain correct and relevant.

> > - I'm glad you're adding SPDX lines, but do you know that the license is
> >   correct in each case?  It's best to be careful with such things.  
> 
> None of the files have licenses so I think we just fall back to COPYING
> don't we? In which case GPL-2.0 is correct for all files.

That's often the best choice, though some people have resorted to some
rather more in-depth archeology to try to figure out what the original
author actually intended.  Again, I'm just asking so that we're sure it's
the best choice.

Thanks,

jon