Hi Timo,
Timo wrote on Sat, Jan 23, 2016 at 10:46:55AM +0200:
> On 23/01/2016 10:44, Martijn van Duren wrote:
>> On 01/23/16 09:35, Timo wrote:
>>> Hi who is responsible for writing documentation for OpenBSD?
>>> I'd like to get involved in writing documentation for OpenBSD
Nice to hear that. If i were to focus on improving OpenBSD
documentation, i could off the top of my head name work that needs
to be done of at least a full-time man-year, probably more.
>>> as I really like OpenBSD and I feel technical writing is one of
>>> my strong points.
Nobody can tell you what you are able to do until we have seen some
of your work, in the sense of committed OpenBSD patches.
>> The best way would be to just start writing patches where you think
>> documentation is lacking and submit them to tech@. There is not one
>> person responsible for writing the documentation.
> Ok makes sense. I'll look over the documentation and see if I find
> something I can contribute to.
Good. Note that though there are lots and lots of defects, finding
them may seem daunting to a beginner. Don't be discouraged if you
search for a few days in random places and find none. If you do find
small, local defects, just send the patches.
The reason why that's so hard is that developers sometimes do it
to chill out, to take a break from coding, and that jmc@ specializes
in it and finds almost every simple defect almost instantly. Also,
if you are interested in how to find technical flaws in manual page
sorce code, look at the "quality control" chapter of my EuroBSDCon
2014 tutorial (both available as PDF and on YouTube). What is
described there is mostly stuff that was already done in the past,
so to find more issues, you usually need to look harder than that.
There largest well-known documentation defects are:
1. LibreSSL documentation. It is way below OpenBSD standards in
almost each and every aspect (correctness, completeness, clarity,
style, formatting), even the parts that were already converted
to mdoc(7).
2. Documentation of standards conformance in section 3 manuals.
Outdated almost everywhere, in literally thousands of manuals.
In is not 100% clear how exactly to fix that, but i'd say:
If C and POSIX agree, list C only. If specified in multiple C
standards, list both the oldest and the newest. If POSIX
needs to be mentioned, usually discuss the most recent version
only.
3. Software that is half third-party, that is, maintained in tree,
but sometimes partially synced with an external source. Working
on such stuff requires synching documentation for subtly different
versions and working with both us and the other project. For
example, multiple people already tried to fix the mess of the
editline(3) documentation, but always ran away before getting
any real work done.
4. Converting the FAQ to a set of manual pages.
There are more projects of that kind. Most require code reading
skills. Most require non-trivial coordination with developers.
On such large projects, don't spend large amounts of times without
talking to someody at the latest after the first day of working,
showing what you did, and be prepared that you may have to start
over two or three times to get it right. Even i would probably
have to throw away my first one or two tries. You will almost
certainly head out in the wrong direction even with these hints.
If you want to start with something really simple, identify your
favourite software from ports. Chances are it has no manual pages,
or bad ones that are very easy to improve. Do a sample of your
work on it (not more than a day) and send it to me. Then i'll get
a better idea of what you are capable of. If you do good work, we
can try to get it upstream, and then identify a good project for
you to work on.
Yours,
Ingo
