(Added linux-doc to Cc and a few people to Bcc)
On 16/06/2023 19:48, Jonathan Corbet wrote:
The documentation discussion at past kernel summits has been lively, so
I think we should do it again. Some topics I would bring to a session
this year would include:
- The ongoing restructuring of the Documentation/ directory. I've been
slowly moving the architecture docs into Documentation/arch/, but
would like to do more to reduce the clutter of the top-level directory
and make our documentation tree more closely resemble the organization
of the source.
- Structure. We continue to collect documents, but do little to tie
them together into a coherent whole. Do we want to change that and,
if so, how?
- Support for documentation work. There is nobody in the community who
is paid to put any significant time into documentation, and it shows.
How can we fix that?
- Infrastructure. Sphinx brings a lot but is far from perfect; what can
we do to improve it?
Other topics will certainly arise as well.
Hi,
This is coming a bit late, but I saw that there is going to be a session
on kernel documentation on the 15th [1] and I wanted to contribute a few
thoughts before that.
First of, regarding the structure, what is the best way to contribute
such changes? Large structural changes would presumably be a patch
series potentially touching a lot of documents from different subsystems
and the individual patches won't necessarily make sense in isolation.
How do we gather consensus for big changes like that? Is it better to
collect acks from subsystem maintainers and then let the documentation
maintainer merge it all at once? Should all the maintainers be Cc'ed on
the cover letter and their individual patches or do they want to be
Cc'ed on everything? What if one or two maintainers don't agree with the
overall approach, does that block the whole series? Does the
documentation maintainer have a veto? Or do we prefer trickle of small,
incremental patches, going through the individual maintainers? Ideally,
I'd like to see these questions answered in the documentation
subsystem's maintainer entry -- it has a paragraph about the boundaries
of documentation being "fuzzier than normal", but it doesn't offer much
practical or actionable advice IMHO.
Speaking of maintainer entry profiles, for those who aren't aware, here
is the description from [2]:
"""
The Maintainer Entry Profile supplements the top-level process documents
(submitting-patches, submitting drivers...) with
subsystem/device-driver-local customs as well as details about the patch
submission life-cycle. A contributor uses this document to level set
their expectations and avoid common mistakes; maintainers may use these
profiles to look across subsystems for opportunities to converge on
common practices.
"""
We currently only have 7 of these and I think it would be great to
spread awareness of their existence so that we can have more. Please
mention this if there is a room full of subsystem maintainers ;-)
I also think it would be great if we could amend these with
subsystem-specific review checklists. I'm thinking of very hands-on
code-technical things that maintainers will be checking in all their
incoming patches, things that aren't obvious and don't necessarily show
up easily in testing -- things like: for new /proc entries, is extra
permission checking done at ->open() or ->write() time? (This is a
non-obvious potential security issue.) The idea here is for maintainers
to document how they review patches to _their_ subsystems and thus also
make it easier for others (outsiders, newcomers) to review for those
same things. I know it would give me more confidence, actually both when
submitting my own patches and potentially also when reviewing others'
patches. One potential issue here is deciding whether certain things fit
better with the Core API and Driver API sections of the documentation --
for example, should subsystem-specific lock nesting orders be part of a
review checklist or does that belong in the source files themselves? How
do we avoid duplication and things getting stale? Can we add a new
kerneldoc directive that gets collected from the C sources and
automatically put into a subsystem-specific review checklist? (I'd be
happy to try implementing this, if people like the idea.)
On the topic of the overall structure of the documentation: [4]
describes the idea that the kernel documentation is set of "books" --
user and admin guide, core API, drivers API, userspace API. I think this
needs to be emphasized more, as that _is_ the (philosophy of the)
current high-level organization of the documentation and it feels a bit
hidden where it currently is; maybe it should be placed prominently at
the top of that file and called "Organization and philosophy" or
something. At least I was very confused when I came across a passage
that read something like "This book covers ..." and I had no idea why a
kernel document was talking about books.
Finally, I'd like to suggest a number of specific structural changes:
1. the HTML sidebar is a bit of an unreadable mess, at least with the
current alabaster theme (the sphinx_rtd_theme is better in this respect,
IMHO, but that's a separate topic). I think the top-level front page
sidebar should _only_ contain the "books", and then you can click
through/expand to the section that you need. As an example, the
front-page sidebar is currently showing firmware-related documentation,
which seems quite out-of-place to me. In a way, we should think of the
documentation tree as a data structure that is optimized for lookups,
and it should be balanced accordingly: each level of the tree needs to
have an appropriate number of nodes (fanout) and firmware belongs
somewhere deeper down. The "books" are a good guide here, since the
division essentially asks: are you a user, a userspace developer, or a
kernel developer? and would allow you to traverse one "level" of the
tree without having to scan through a dozen different sections that
conceptually belong _after_ that first question of who you are.
2. some documents currently exist at multiple places in the toctree. As
an example, "Core API Documentation" is available from both "Internal
API manuals" and "Internal API manuals -> Kernel subsystem documentation
-> Core subsystems" (i.e. both Documentation/index.rst and
Documentation/subsystem-apis.rst). This is both weird and confusing from
a navigational point of view; it's as if a real book had 20 chapters at
the beginning but also the exact same chapters nested deeply inside
another chapter somewhere else in the book. We should be using
cross-referencing instead. Moreover, do we have a way to detect these
multiple inclusions (e.g. a sphinx-build warning)?
3. I'm wondering if it wouldn't be appropriate to have a top-level
"Community" book (maybe even the very first one) that would detail
things like the CoC, mailing lists and etiquette (but not
process-oriented details like how to submit a patch; we should link to
those, though!), references to IRC channels and social.kernel.org,
kernelnewbies.org, maybe eventually other things like governance
structure, etc. The main idea here is to put the community in focus, as
I think that's something we're lacking slightly -- the kernel community
is large and diverse and in many ways highly fractured. Many things are
not written anywhere at all and other things that are written somewhere
are maybe scattered all over the place. By having a dedicated place to
put community-related documentation it would show that this is something
we actually care about and make the kernel more welcoming to newcomers
and outsiders.
4. "translations" also doesn't need to be a top-level document that
appears in the top-level sidebar; in [5] I submitted a Sphinx extension
that would add a language selection bar to the top of the rendered HTML,
which would allow you to change the language of _any_ document that has
translations, including the front page. I'll still need to submit my v2
of this.
5. I think architecture-specific information should be split up along
the user+admin/userspace-dev/kernel-dev lines and moved into their
respective books instead of being a top-level document. This goes
counter to the idea that Documentation/ should mirror the structure of
the kernel sources, but I think it makes sense to make an exception in
this case.
Vegard
[1] <https://lpc.events/event/17/contributions/1622/>
[2] <https://docs.kernel.org/maintainer/maintainer-entry-profile.html>
[3] <https://github.com/sphinx-doc/sphinx/issues/10966>
[4]
<https://docs.kernel.org/doc-guide/contributing.html#documentation-coherency>
[5]
<https://lore.kernel.org/linux-doc/20231028162931.261843-1-vegard.nossum@xxxxxxxxxx/>
