Hi Stephen,
Post by Stephen GregorattoI've recently been getting into (re)writing my manpages using mdoc(7),
and came across Ingo's talk about mandoc/LibreSSL [1]. In it he
mentioned that there are still some functions to document and many
pages need a couple of goes over (specifically openssl(1)).
Now I've never developed for Open/LibreSSL,
That will make the learning curve significantly steeper, but it should
still be possibly to help. You should expect to spend considerable
amounts of time learning how the features you are trying to document
work, though, in addition to the time needed to work on the text itself.
Post by Stephen Gregorattoand have an OK knowledge of C,
That is good.
Post by Stephen Gregorattobut I do have a bit of free time over Christmas
If you never plan to come back to the project in 2019 or later, i
have some doubts as to how much you can get done. If one or two
weeks is all the time you have to spend, most of that will be used
up learning about LibreSSL, mdoc, and about how OpenBSD development
works in general.
If you have some time now and are not yet sure whether you might
be interested to work again on it in the future but consider that
possible, just try.
Post by Stephen Gregorattoand would be happy to help out in any way.
That's quite welcome.
Post by Stephen GregorattoWould I need to fully grok the code before I could write the docs?
Absolutely not. You could spend an infinite amount of time to
understand the code if you tried to understand everything.
Of course, there is nothing wrong with studying whatever interests
you.
But if your main goal is to improve the docs, you only need to look
at the code when it is unclear what a given feature does or how it
must be used, and you only need to understand enough of the code
such that you can can answer these two questions.
Judging from how you describe your knowledge and experience,
i (wildly) *guess* that the main challenges might be:
* Figuring out what are gaps in the documentation and what is
intentionally undocumented (as i explained in the talk, that's
a serious problem for anyone, even for me, heck, even for jsing@).
* Getting used to the style of OpenBSD documentation (assuming i
understand correctly that you never provided significant
contributions to OpenBSD docs before). You can't learn that
style from LibreSSL docs because they are written in a different
style, in OpenSSL style. The only way to learn that style is
trial and error, discussing your patches with OpenBSD developers,
and occasionally looking at OpenBSD libc section 2 and section 3
manual pages.
* Getting used to the way OpenBSD development works. You learn
that by sending patches and listening to the feedback.
* Getting used to the mdoc(7) languange. You learn that by
reading mdoc(7), sending patches, and listening to the feedback.
It's likely the least of the challenges.
Now, where should you start, both in the sense of choosing a subject
area and in the sense of choosing a working style?
Regarding the subject area / sub-library: if there is an area you
are personally interested in, start with that. Otherwise, consider
starting with something that is important (BN_*, EVP_*, RSA_*) or
modern (EC*, TLS 1.3). If you ever enter into a coversation with
jsing@ over one of your patches, ask him what is most urgent.
Possible working styles depend on what you are best at.
* Copy editing: read existing manuals, improve the style,
make it more concise, more precise, clearer, close gaps.
Also fix the order of information.
Needed almost everywhere.
Works best with a strong understanding of OpenBSD manual style.
* New pages: take an important or modern sub-library, look at the
public headers and identify undocumented functions. Check with
LibreSSL developers which ones should be documented. Write
new manuals. Needed almost everywhere.
Requires moderate experience writing function manuals from scratch.
* Hunting for bugs: compare docs and code and identify contradictions
between both: mismatches between argument types in the *.h, *.c,
and *.3 files, mismatches of return types, wrong .In lines,
typos in function names or other parts of prototypes, statements
about behaviour or usage that contradict the code.
Can be tedious and take quite some time with little visible
results, but requires less experience and has the side-effect
of building familiarity with the code and docs.
Note that the page openssl(1) is a special case. It already had
basic copy editing by jmc@ regarding style and language, but it
could use more checking and improving of the content. Since it is
merely a testing tool, it is not the most important part; the reason
for mentioning it in the talk was that it is a part that so far had
less review than other parts, no matter the importance.
If you still don't have a clear preference how to start, one useful
approach that i'd recommend is to go through recent LibreSSL commits
in reverse chronological order (that makes sure what you do is at
least of some relevance). For each commit, figure out whether it
has user-visible consequences. If so, check whether the docs
correctly describe how the library works after the commit in this
respect. If not, send patches to fix the docs. Also, send patches
for any other bugs or gaps that you discover in the process.
Even if you want to pick a different working style, going through
recent commits can still serve to choose a subject area / sub-library:
If an area got at least a handful of non-trivial commits during the
last year, it is likely worth working on.
Good luck,
Ingo