Add a document on how to contribute to the documentation
Jonathan Corbet
maintainerPATCH v2 1/1 Add a document on how to contribute to the documentation
This is mostly a collection of thoughts for how people who want to help out can make the docs better. Hopefully the world will respond with a flurry of useful patches.
---
Changes since v1
- Add section on orphaned kerneldoc comments
- Try to head off oxford-comma comments
- A few small wording tweaks
- Visions of singing angels deferred to a future patch
Documentation/doc-guide/contributing.rst | 294 +++++++++++++++++++++++ Documentation/doc-guide/index.rst | 1 + 2 files changed, 295 insertions(+) create mode 100644 Documentation/doc-guide/contributing.rst
(quoted diff) +0 -0
b/Documentation/doc-guide/contributing.rst new file mode 100644 index 000000000000..10956583d22e
Documentation/doc-guide/contributing.rst new file +7 -0
@@ -0,0 +1,294 @@ +.. SPDX-License-Identifier: GPL-2.0 +How to help improve kernel documentation +======================================== + +Documentation is an important part of any software-development project. +Good documentation helps to bring new developers in and helps established +developers work more effectively. Without top-quality documentation, a
lot +of time is wasted in reverse-engineering the code and making avoidable +mistakes.
+
+Unfortunately, the kernel's documentation currently falls far short of what +it needs to be to support a project of this size and importance. +
+This guide is for contributors who would like to improve that situation. +Kernel documentation improvements can be made by developers at a variety of +skill levels; they are a relatively easy way to learn the kernel process in +general and find a place in the community. The bulk of what follows is the +documentation maintainer's list of tasks that most urgently need to be +done.
+
+The documentation TODO list
+---------------------------
+
+There is an endless list of tasks that need to be carried out to get our +documentation to where it should be. This list contains a number of +important items, but is far from exhaustive; if you see a different way to +improve the documentation, please do not hold back!
+
+Addressing warnings
+~~~~~~~~~~~~~~~~~~~
+
+The documentation build currently spews out an unbelievable number of +warnings. When you have that many, you might as well have none at all; +people ignore them, and they will never notice when their work adds new +ones. For this reason, eliminating warnings is one of the highest-priority +tasks on the documentation TODO list. The task itself is reasonably +straightforward, but it must be approached in the right way to be +successful.
+
+Warnings issued by a compiler for C code can often be dismissed as false +positives, leading to patches aimed at simply shutting the compiler up. +Warnings from the documentation build almost always point at a real +problem; making those warnings go away requires understanding the problem +and fixing it at its source. For this reason, patches fixing documentation +warnings should probably not say "fix a warning" in the changelog title; +they should indicate the real problem that has been fixed. +
+Another important point is that documentation warnings are often created by +problems in kerneldoc comments in C code. While the documentation +maintainer appreciates being copied on fixes for these warnings, the +documentation tree is often not the right one to actually carry those +fixes; they should go to the maintainer of the subsystem in question. +
+For example, in a documentation build I grabbed a pair of warnings nearly +at random::
+
+ ./drivers/devfreq/devfreq.c:1818: warning: bad line: + - Resource-managed devfreq_register_notifier() + ./drivers/devfreq/devfreq.c:1854: warning: bad line:
+ - Resource-managed devfreq_unregister_notifier()
+
+(The lines were split for readability).
+
+A quick look at the source file named above turned up a couple of kerneldoc +comments that look like this::
+
+ /**
+ * devm_devfreq_register_notifier() + - Resource-managed devfreq_register_notifier() + * @dev: The devfreq user device. (parent of devfreq) + * @devfreq: The devfreq object. + * @nb: The notifier block to be unregistered. + * @list: DEVFREQ_TRANSITION_NOTIFIER. + */
+
+The problem is the missing "*", which confuses the build system's +simplistic idea of what C comment blocks look like. This problem had been +present since that comment was added in 2016 — a full four years. Fixing +it was a matter of adding the missing asterisks. A quick look at the +history for that file showed what the normal format for subject lines is, +and ``scripts/get_maintainer.pl`` told me who should receive it. The +resulting patch looked like this::
+
+ [PATCH] PM / devfreq: Fix two malformed kerneldoc comments
+
+ Two kerneldoc comments in devfreq.c fail to adhere to the required format,
+ resulting in these doc-build warnings:
+
+ ./drivers/devfreq/devfreq.c:1818: warning: bad line:
+ - Resource-managed devfreq_register_notifier()
+ ./drivers/devfreq/devfreq.c:1854: warning: bad line:
+ - Resource-managed devfreq_unregister_notifier()
+
+ Add a couple of missing asterisks and make kerneldoc a little happier. +
+ Signed-off-by: Jonathan Corbet <[email protected]>
+ ---
+ drivers/devfreq/devfreq.c | 4 ++--
+ 1 file changed, 2 insertions(+), 2 deletions(-)
+
+ diff --git a/drivers/devfreq/devfreq.c b/drivers/devfreq/devfreq.c + index 57f6944d65a6..00c9b80b3d33 100644 + --- a/drivers/devfreq/devfreq.c + +++ b/drivers/devfreq/devfreq.c + @@ -1814,7 +1814,7 @@ static void devm_devfreq_notifier_release(struct
device *dev, void *res) +
+ /**
+ * devm_devfreq_register_notifier()
+ - - Resource-managed devfreq_register_notifier()
+ + * - Resource-managed devfreq_register_notifier()
+ * @dev: The devfreq user device. (parent of devfreq) + * @devfreq: The devfreq object. + * @nb: The notifier block to be unregistered.
+ @@ -1850,7 +1850,7 @@ EXPORT_SYMBOL(devm_devfreq_register_notifier); +
+ /**
+ * devm_devfreq_unregister_notifier()
+ - - Resource-managed devfreq_unregister_notifier()
+ + * - Resource-managed devfreq_unregister_notifier()
+ * @dev: The devfreq user device. (parent of devfreq) + * @devfreq: The devfreq object. + * @nb: The notifier block to be unregistered.
+ --
+ 2.24.1
+
+The entire process only took a few minutes. Of course, I then found that +somebody else had fixed it in a separate tree, highlighting another
lesson: +always check linux-next to see if a problem has been fixed before you dig +into it.
+
+Other fixes will take longer, especially those relating to structure +members or function parameters that lack documentation. In such cases, it +is necessary to work out what the role of those members or parameters is +and describe them correctly. Overall, this task gets a little tedious at +times, but it's highly important. If we can actually eliminate warnings +from the documentation build, then we can start expecting developers to +avoid adding new ones.
+
+Languishing kerneldoc comments
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Developers are encouraged to write kerneldoc comments for their code, but +many of those comments are never pulled into the docs build. That makes +this information harder to find and, for example, makes Sphinx unable to +generate links to that documentation. Adding ``kernel-doc`` directives to +the documentation to bring those comments in can help the community derive +the full value of the work that has gone into creating them.
+
+The ``scripts/find-unused-docs.sh`` tool can be used to find these +overlooked comments.
+
+Note that the most value comes from pulling in the documentation for +exported functions and data structures. Many subsystems also have +kerneldoc comments for internal use; those should not be pulled into the +documentation build unless they are placed in a document that is +specifically aimed at developers working within the relevant subsystem. +
+
+Typo fixes
+~~~~~~~~~~
+
+Fixing typographical or formatting errors in the documentation is a quick +way to figure out how to create and send patches, and it is a useful +service. I am always willing to accept such patches. That said, once you +have fixed a few, please consider moving on to more advanced tasks, leaving +some typos for the next beginner to address.
+
+Please note that some things are *not* typos and should not be "fixed":
+
+ - Both American and British English spellings are allowed within the
+ kernel documentation. There is no need to fix one by replacing it with
+ the other.
+
+ - The question of whether a period should be followed by one or two spaces
+ is not to be debated in the context of kernel documentation. Other + areas of rational disagreement, such as the "Oxford comma", are also + off-topic here.
+
+As with any patch to any project, please consider whether your change is +really making things better.
+
+Ancient documentation
+~~~~~~~~~~~~~~~~~~~~~
+
+Some kernel documentation is current, maintained, and useful. Some +documentation is ... not. Dusty, old, and inaccurate documentation can +mislead readers and casts doubt on our documentation as a whole. Anything +that can be done to address such problems is more than welcome. +
+Whenever you are working with a document, please consider whether it is +current, whether it needs updating, or whether it should perhaps be removed +altogether. There are a number of warning signs that you can pay attention +to here:
+
+ - References to 2.x kernels
+ - Pointers to SourceForge repositories
+ - Nothing but typo fixes in the history for several years
+ - Discussion of pre-Git workflows
+
+The best thing to do, of course, would be to bring the documentation +current, adding whatever information is needed. Such work often requires +the cooperation of developers familiar with the subsystem in question, of +course. Developers are often more than willing to cooperate with people +working to improve the documentation when asked nicely, and when their +answers are listened to and acted upon.
+
+Some documentation is beyond hope; we occasionally find documents that +refer to code that was removed from the kernel long ago, for example. +There is surprising resistance to removing obsolete documentation, but we +should do that anyway. Extra cruft in our documentation helps nobody. +
+In cases where there is perhaps some useful information in a badly outdated +document, and you are unable to update it, the best thing to do may be to +add a warning at the beginning. The following text is recommended:: +
+ .. warning ::
+ This document is outdated and in need of attention. Please use
+ this information with caution, and please consider sending patches
+ to update it.
+
+That way, at least our long-suffering readers have been warned that the +document may lead them astray.
+
+Documentation coherency
+~~~~~~~~~~~~~~~~~~~~~~~
+
+The old-timers around here will remember the Linux books that showed up on +the shelves in the 1990s. They were simply collections of documentation +files scrounged from various locations on the net. The books have (mostly) +improved since then, but the kernel's documentation is still mostly built +on that model. It is thousands of files, almost each of which was written +in isolation from all of the others. We don't have a coherent body of +kernel documentation; we have thousands of individual documents. +
+We have been trying to improve the situation through the creation of +a set of "books" that group documentation for specific readers. These +include:
+
+ - :doc:../admin-guide/index
+ - :doc:../core-api/index
+ - :doc:../driver-api/index
+ - :doc:../userspace-api/index
+
+As well as this book on documentation itself.
+
+Moving documents into the appropriate books is an important task and needs +to continue. There are a couple of challenges associated with this work, +though. Moving documentation files creates short-term pain for the people +who work with those files; they are understandably unenthusiastic about +such changes. Usually the case can be made to move a document once; we +really don't want to keep shifting them around, though.
+
+Even when all documents are in the right place, though, we have only +managed to turn a big pile into a group of smaller piles. The work of +trying to knit all of those documents together into a single whole has not +yet begun. If you have bright ideas on how we could proceed on that front, +we would be more than happy to hear them.
+
+Stylesheet improvements
+~~~~~~~~~~~~~~~~~~~~~~~
+
+With the adoption of Sphinx we have much nicer-looking HTML output than we +once did. But it could still use a lot of improvement; Donald Knuth and +Edward Tufte would be unimpressed. That requires tweaking our stylesheets +to create more typographically sound, accessible, and readable output. +
+Be warned: if you take on this task you are heading into classic bikeshed +territory. Expect a lot of opinions and discussion for even relatively +obvious changes. That is, alas, the nature of the world we live in. +
+Non-LaTeX PDF build
+~~~~~~~~~~~~~~~~~~~
+
+This is a decidedly nontrivial task for somebody with a lot of time and +Python skills. The Sphinx toolchain is relatively small and well +contained; it is easy to add to a development system. But building PDF or +EPUB output requires installing LaTeX, which is anything but small or well +contained. That would be a nice thing to eliminate.
+
+The original hope had been to use the rst2pdf tool (https://rst2pdf.org/)
+for PDF generation, but it turned out to not be up to the task. +Development work on rst2pdf seems to have picked up again in recent times, +though, which is a hopeful sign. If a suitably motivated developer were to +work with that project to make rst2pdf work with the kernel documentation +build, the world would be eternally grateful.
+
+Write more documentation
+~~~~~~~~~~~~~~~~~~~~~~~~
+
+Naturally, there are massive parts of the kernel that are severely +underdocumented. If you have the knowledge to document a specific kernel +subsystem and the desire to do so, please do not hesitate to do some +writing and contribute the result to the kernel. Untold numbers of kernel +developers and users will thank you.
(quoted diff) +0 -0
b/Documentation/doc-guide/index.rst index 603f3ff55d5a..c58de84c0d5b 100644
Documentation/doc-guide/index.rst +1 -0
@@ -10,6 +10,7 @@ How to write kernel documentation sphinx kernel-doc parse-headers + contributing .. only:: subproject and html
Signature · 1 line
2.24.1
Quoted 8 lines · Jonathan Corbet
Documentation/doc-guide/contributing.rst new file +6
-0+How to help improve kernel documentation +======================================== + +Documentation is an important part of any software-development project. +Good documentation helps to bring new developers in and helps established +developers work more effectively. Without top-quality documentation, alot +of time is wasted in reverse-engineering the code and making avoidable +mistakes.
Your mailer has done something weird to the wrapping there (and throughout).