Let’s make manuals more useful, part 1 - Ingo Schwarze

Who should take this course:

This course is intended for the following audiences. For each group, the topic numbers that will be of the most immediate interest are listed, but the other topics are likely to be useful as well.

Software developers, since no software is complete without documentation – in particular, but not limited to, developers of publicly available, portable software. (1, 2, 3, 4, 0)
Operating system developers, since all operating system development and maintenance includes keeping the system’s native documentation, and the tools handling it, up to date. (5, 6, 7, 3, 4, 0)
Porters, that is, people porting software to a given operating system and providing ports and packages. Such work usually requires dealing with a wide variety of documentation formats. (6, 7, 3, 2, 4)
Documentation developers, that is, people specifically working on software manuals, even if they are not developing the software itself. (0, 1, 2, 3, 4, 7)
System administrators, to understand how documentation is written, built, installed, and indexed for searching, to help troubleshooting and supporting their users. (6, 2, 4, 1, 7)
Some end users of computers running BSD operating systems may also find the course interesting to better understand how to use documentation search and display tools and to get some background on how these tools, and documentation formatting and installation in general, works. (4, 0, 1, 7)
Attendants are expected to have basic experience using the command-line user interface of UNIX-like operating systems. 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.

Ingo Schwarze will try to keep the content accessible for newcomers to the field of documentation formatting, but to also cover the newest developments and tools that specialists in the field will be interested in.

If participants drop Ingo Schwarze a mail beforehand to, preferably right after registering, stating their background and/or what they are most interested in, he can use such information to tune the course content towards the audience.

Description:

Manual pages have been a resource of critical importance in UNIX for more than 40 years, since Version 1 AT&T UNIX. The steady evolution of the mandoc toolbox during the last six years allows to leverage the various strengths of the concept much better than in the past and to deliver more useful documentation.
(0) The course will start with a brief introduction explaining what these strengths are, and providing some historical background.
After that, it will teach:

(1) How to get started using the mdoc(7) formatting language for writing new software manuals, how to do so without spending too much time learning the language, and which resources to use while working on mdoc(7) manuals.
(2) How to make sure that mdoc(7)-based documentation in a portable software distribution is portable, using the mandoc(1) -Tman output mode and the ./configure mechanism.
(3) How to support quality control of existing manuals using mandoc(1) – Tlint and other tools.
At about this point, there will be a working phase with hands-on exercises.

(4) How to use the mandoc-based apropos(1) search tool and how to build its databases with makewhatis(8).
(5) How to effectively integrate mandoc(1) as a manual formatter and manual page search system into the base system of a BSD operating system and what to pay attention to while doing so
(6) How to effectively use mandoc(1) as a manual formatter and manual page search system in a porting and packaging framework, and what to do about manuals that require groff(1) for correct formatting.
(7) Which next steps are recommended for the major BSD systems: OpenBSD, NetBSD, FreeBSD, DragonFly, …
Depending on what Ingo Schwarze gets done in mandoc development during the summer, he is likely to add one or two surprise topics to the course showing the latest developments.

Speaker biography:

Ingo Schwarze has been an OpenBSD user since 2001 and a developer
since 2009. He maintains the OpenBSD in-tree mandoc since making
it the only documentation formatter in the base system in 2009/2010.
He also maintains the portable mandoc distribution since 2013 and
the OpenBSD groff(1) port since 2010 and has contributed to various
parts of the OpenBSD userland, for example the Perl rewrite of the
security(8) script, as well as smaller contributions to man(1), to
the rc.d(8) framework, the yp(8) subsystem, the C library, and
various other programs. Outside the free software world, he studied
physics in Siegen/Germany and worked as a researcher in elementary
particle physics at CERN and at the University of Karlsruhe (KIT),
and as a Perl programmer for Sophos UTM.