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 <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 +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.
> 

Reply via email to