Re: man 9 intro - improvements [and learning for me]?
--- Original Message --- On Tuesday, September 19th, 2023 at 7:03 PM, Theo de Raadt wrote: > > > Ingo, that's a bit cynical. > > > As long as the process is slow, step by step, adding one or two manuals at > a time, and focusing on being ACCURATE, then it will be good. > > It would be wrong to add inaccurate pages. A lack of documentation is slightly > better than inaccurate documentation. > > So if you really want to do this, I suggest you start with the simplest ones > first, get them correct, listen to the feedback you receive and figure out > who has knowledge in each area, and adapt your review process along the way. > > Ingo is very familiar with this process, but perhaps also a bit jaded because > he has done some very big documentation uplifts (and in each case, had the > big plan to update a big area). Done in small bits, small but valuable > improvements are not that difficult. > I appreciate the course correction with my approach and train of thought. Instead of just updating something for the sake of updating it, ensure it is solid as you go and useful. So, for example, if I'm diving into some portion of the kernel and find the documentation lacking in some manner, best to call that out with a proposed change (which I'm sure will not be good enough the first go around). I am fortunate in that I have a perspective of being new to this space, so I can see it from a different POV than you seasoned vets here. No one likes doc-rot and I don't want to be a problem-maker in that area. I've maintained enough technical documentation over the years, it is a beast of a burden, and at the end of it all you question why you even started. I've reoriented myself to just focus on one portion [perhaps of a portion] to focus on and learn at a time. Not trying to be the world's greatest kernel developer and documentation expert. Just learning to learn and have fun by working on dope stuff you all built. My coding in C is rusty at best (though I used to code it for a living) and I certainly know little about writing and editing man pages. Appreciate the guidance and advice. It is helpful to be aligned properly with you all and your expectations of how quality work is done and approached. > Ingo Schwarze schwa...@usta.de wrote: > > > 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 +: > > > > > 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
Re: man 9 intro - improvements [and learning for me]?
Ingo, that's a bit cynical. As long as the process is slow, step by step, adding one or two manuals at a time, and focusing on being ACCURATE, then it will be good. It would be wrong to add inaccurate pages. A lack of documentation is slightly better than inaccurate documentation. So if you really want to do this, I suggest you start with the simplest ones first, get them correct, listen to the feedback you receive and figure out who has knowledge in each area, and adapt your review process along the way. Ingo is very familiar with this process, but perhaps also a bit jaded because he has done some very big documentation uplifts (and in each case, had the big plan to update a big area). Done in small bits, small but valuable improvements are not that difficult. Ingo Schwarze wrote: > 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 +: > > > 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. >
Re: man 9 intro - improvements [and learning for me]?
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 +: > 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.
Re: man 9 intro - improvements [and learning for me]?
On Mon, Sep 18, 2023 at 12:21:48PM +, Christoff Humphries wrote: > Greetings all. > > 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? > > 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 ."). > > 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. > > Thanks in advance! > hi. as far as i know, there is no real kernel overview page. so i guess intro(9) would be the place. you could certainly try to do something similar to netbsd's page - it would be more useful than what we have now. jmc
man 9 intro - improvements [and learning for me]?
Greetings all. 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? 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 ."). 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. Thanks in advance!
