Re: [TECH TOPIC] Kernel documentation

Re: [TECH TOPIC] Kernel documentation

[Vegard Nossum]

On 11/11/2023 16:14, Jonathan Corbet wrote:
> Vegard Nossum <vegard.nossum@oracle.com> writes:
>> The Maintainer Entry Profile supplements the top-level process
>> documents
[...]
>> 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 routinely mention it at the maintainers summit...progress is slow.

I saw that a maintainer entry profile is coming soon for ext4 (yay!):

   https://lore.kernel.org/workflows/20231119225437.GA292450@mit.edu/

I also recall the question/discussion from your talk about whether move
some of the documentation closer to their subsystems. Maybe the
maintainer entry profiles would be an ideal candidate to try this out as
an experiment? The advantages would be:

1) there's very few existing documents, so moving these into their
respective directories should cause relatively little churn,

2) probably no document is more tied to a specific subsystem than the
maintainer entry profiles,

3) it would hopefully yield far more visibility for these documents,
which would aid patch submitters as well as potentially inspire more
subsystems to add them.

I tried it out quickly, but Sphinx doesn't really like having documents
outside of the root -- how about just using symlinks? e.g.:

     ln -rs Documentation/filesystems/xfs-maintainer-entry-profile.rst 
fs/xfs/MAINTAINER-ENTRY-PROFILE.rst

I don't really see any downsides... thoughts?


Vegard