Hi Christoff, of course you are free to work on whatever interests you, but if you are looking for advice, i'd respectfully recommend that you try to work on specifics rather than on generalities first, in particular when you feel as if your experience in contributing isn't above average. That applies even in the domain of documentation.
Christoff Humphries wrote on Mon, Sep 18, 2023 at 12:21:48PM +0000: > I went searching for documentation about the kernel internals and was > used to the intro(9) man page from NetBSD > https://man.netbsd.org/intro.9 that had a lot more details. Would it > be a worthwhile project to attempt to do the same for OpenBSD? Doing something like that may *sound* simple at first, but actually, i can think of few documentation changes that would be harder to get right and harder to get committed. Unless i'm totally off track, getting that right requires 1) a solid understanding of all areas of the kernel and 2) a good understanding of what our kernel developers actually need to know for their everyday work. If you have that knowledge, it's *still* much easier to improve individual pages that are lacking in quality than improving the top-level overview. Note that item 2 above tells you which of the pages are probably most worthy of attention. Besides, the NetBSD intro(9) page does not strike me as particularly convincing. *If* the lines in that page agree with the .Nd one-line descriptions in the indivual pages, then it provides almost nothing of value - but causes a maintenance burden because it needs to be edited whenever any .Nd line changes. If the lines mismatch, then the .Nd lines in the indivifual pages can likely be improved. I did not check which is the case - possibly both are. We did have a few pages like that in the past, but most of those got deleted because they provided little value. For example, compare these two: https://man.openbsd.org/OpenBSD-5.6/string.3 https://man.openbsd.org/OpenBSD-current/string.3 A very small number still exists, perhaps most notably https://man.openbsd.org/crypto.3 and https://man.openbsd.org/ssl.3 The benefit of those is *not* that they exhaustively list everything - indeed, apropos(1) is better at that job than a manually maintained table of contents - but that they provide some high-level information how the libraries as a whole are intended to be used that is hard to figure out from individual pages. Also, these pages do not duplicate .Nd lines. > I understand the annoyance of folks talking about what they intend or > are going to do with no actual fruit, but wanted to check that the > intro(9) is lacking and the information is not just stored somewhere > else (other than "apropos -s 9 ."). Sorry, i lack the experience in kernel development that would be required to judge whether any information could usefully be added to intro(9). Yours, Ingo > I want to learn the internals of the OpenBSD kernel, too, and will do > as mulander (and friends) did by learning a bit of code daily > https://blog.tintagel.pl/2017/09/10/openbsd-daily-recap.html. > > Seeking the learn and contribute, especially in the uvm, vmd/vmm, and > possibly filesystem subsystems.
