Writing software documentation with mdoc(7)

Who should take this course:
----------------------------
This course is intended for software developers, operating system
developers, software porters, documentation developers and system
administrators seeking to improve their skills at writing and
maintaining software documentation using the BSD mdoc(7) semantic
markup and formatting language supported by both the mandoc(1)
and groff(1) toolboxes and used as the main documentation language
in OpenBSD, FreeBSD, NetBSD, DragonFly, and illumos.

The intention is to both help beginners getting started as well as
offer advanced exercises for authors already having some experience
with the mdoc(7) language.  Participants are expected to have basic
experience using the command-line user interface of UNIX-like
operating systems.  To profit most from the course, please bring
a notebook running any of the above operating systems or Linux,
Minix 3, or MacOS X.  For the latter three, please install a recent
version of mandoc(1) from mdocml.bsd.lv before coming to Stockholm.

Basic experience in programming and system administration may help
understanding a few points, but is not required.  Prior knowledge
about documentation formatting and processing tools is not required,
but doesn't hurt either.

If participants drop me a mail beforehand to <schwarze at openbsd
dot org>, preferably right after registering, stating their background
and/or what they are most interested in, i can use such information
to tune the course content towards the audience.

Description:
------------
Every piece of software needs documentation - no matter whether
we are talking about basic tools distributed with operating systems,
stand-alone portable software packages, or private scripts offered
by system administrators to users or other admins of a particular
group of computers.

Together with the man(1) section conventions, the mdoc(7) markup
and formatting language that originated in 4.3BSD-Reno has proven
very simple, versatile, and timelessly useful.  It is the ideal
tool for all the applications mentioned above, and with the continuous
evolution of the mandoc(1) toolbox during the last seven years,
some of its features can now be exploited that lay dormant for more
than two decades.

The course will start with a brief introduction to the history and
advantages of the mdoc(7) language and the possibilities offered
by the mandoc(1) toolbox.  It will then teach how to get started
writing and maintaining mdoc(7) manuals, and it will explore various
topics that regularly cause difficulties for documentation newbies
and more experienced documentation authors alike.