From: Vegard Nossum <vegard.nossum@oracle.com>
To: Jonathan Corbet <corbet@lwn.net>, ksummit@lists.linux.dev
Cc: linux-doc@vger.kernel.org, Theodore Ts'o <tytso@mit.edu>,
workflows@vger.kernel.org
Subject: Re: [TECH TOPIC] Kernel documentation
Date: Mon, 20 Nov 2023 13:20:00 +0100 [thread overview]
Message-ID: <08dee822-c269-41c4-8699-cfab51241e9f@oracle.com> (raw)
In-Reply-To: <87cywg8gpg.fsf@meer.lwn.net>
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
prev parent reply other threads:[~2023-11-20 12:20 UTC|newest]
Thread overview: 23+ messages / expand[flat|nested] mbox.gz Atom feed top
2023-06-16 17:48 [TECH TOPIC] Kernel documentation Jonathan Corbet
2023-06-20 16:02 ` Jani Nikula
2023-06-20 19:30 ` Jonathan Corbet
2023-11-20 12:06 ` Vegard Nossum
2023-11-20 13:50 ` Jonathan Corbet
2023-11-20 14:42 ` Mauro Carvalho Chehab
2023-11-20 14:49 ` Johannes Berg
2023-11-20 20:54 ` Jonathan Corbet
2023-06-29 21:34 ` Intersphinx ([TECH TOPIC] Kernel documentation) Jonathan Corbet
2023-06-30 13:17 ` Jani Nikula
2023-06-30 16:54 ` Theodore Ts'o
2023-06-30 17:11 ` Jonathan Corbet
2023-07-02 1:46 ` Steven Rostedt
2023-07-02 4:56 ` Linus Torvalds
2023-07-02 13:18 ` James Bottomley
2023-07-02 18:32 ` Steven Rostedt
2023-07-02 18:44 ` Linus Torvalds
2023-07-03 2:46 ` Theodore Ts'o
2023-06-21 11:04 ` [TECH TOPIC] Kernel documentation Thorsten Leemhuis
2023-06-26 14:34 ` Jan Kara
2023-11-11 12:42 ` Vegard Nossum
2023-11-11 15:14 ` Jonathan Corbet
2023-11-20 12:20 ` Vegard Nossum [this message]
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
Avoid top-posting and favor interleaved quoting:
https://en.wikipedia.org/wiki/Posting_style#Interleaved_style
* Reply using the --to, --cc, and --in-reply-to
switches of git-send-email(1):
git send-email \
--in-reply-to=08dee822-c269-41c4-8699-cfab51241e9f@oracle.com \
--to=vegard.nossum@oracle.com \
--cc=corbet@lwn.net \
--cc=ksummit@lists.linux.dev \
--cc=linux-doc@vger.kernel.org \
--cc=tytso@mit.edu \
--cc=workflows@vger.kernel.org \
/path/to/YOUR_REPLY
https://kernel.org/pub/software/scm/git/docs/git-send-email.html
* If your mail client supports setting the In-Reply-To header
via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line
before the message body.
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for read-only IMAP folder(s) and NNTP newsgroup(s).