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

From: Jonathan Corbet
Date: Fri Feb 08 2019 - 15:00:39 EST

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.