FreeBSD Documentation: An Interview with Tom Rhodes

by George Rosamond <george at daemonnews dot org>

Right away, appreciating the strength of BSD documentation, it was clear that interviewing Tom for Daemon News would be worthwhile. Most BSD users appreciate the documentation, but few have any idea of what occurs behind the scenes.

Recently, we spoke on Instant Messenger about the FreeBSD Handbook and the process of keeping it clean, comprehensive and relevant.

Tom lives in Pennsylvania.

George: When did you get involved in the FreeBSD project?

Tom Rhodes: About or around three years ago. The CVS logs can show an exact time I became a committer in doc, src, and ports.

George: How did you get involved specifically with the doc part?

Tom Rhodes: Well, I started configuring FreeBSD for a server. I had an interesting error appear on my screen, I don't remember what it was, so I started reading over the Handbook. The Handbook offered an explanation but the steps were incorrect. Finally, after about two hours of debugging, I had reached a point of success with the server. This was my first of a large amount of patches for the docs. I didn't want anyone else to end up in the situation I was in, and I wanted to ensure the information was correct.

George: So did you just contact the maintainers?

Tom Rhodes: At first I sent an email to the docs list, not being a person to just "ask for help without reading." At this point I was asked to send a patch. The information on the docproj website; was a big help in getting started. Before long, I was submitting several patches based on comments from the list members, other committers, and the instructions on the web site.

George: I assume RTFM'ing and browsing the docs list is the first steps anyone should take before posting an issue with the FreeBSD Handbook.

Tom Rhodes: Actually, I think the first step is reading the Handbook, manual page, or an article. If that fails, a Google search will usually always return an answer. An answer to a problem someone has with Linux or perhaps another UNIX variant can easily be applied to FreeBSD. If the Handbook is incorrect, that is when I feel a patch or simple mention of the error on the list is a good thing.

George: How many other people are involved in maintaining the Handbook, including committers?

Tom Rhodes: Including committers, it's hard to say. We have numerous English speakers who always work on the Handbook, and many translation team members who provide feedback and patches to the English version. On an average, we usually have about 15 at any given time. This includes those whom submit patches to us, and those of us who commit them to the Handbook. Makes me wonder how many people are actually subscribed to the mailing list.

It's interesting to note that many times, a patch to the Handbook from the translation team will be applied by someone else; in these cases, there is never a problem report or an email sent to the list.

George: How many languages is the Handbook translated into?

Tom Rhodes: I think about 17 different languages at this time. Many of them in various stages of production. The smaller the translation team, the further behind the English version they are. A point of interest is that the French, German and Russian translations seem to be the best maintained.

George: What is the criteria for adding new sections into the Handbook?

Tom Rhodes: Criteria can be broken down into parts or areas. Any change must at least contain:

A good explanation of the problem including a fix for the issue at hand;

Correct information which is easy to follow and has decent spelling and grammar;

Must provide a fix for both the 4.X and 5.X branches if applicable.

In some cases, a change may only be required to update the information for 5.X while the current documentation is correct for 4.X. In these cases, a simple note or adjustment to the paragraph may be in order. The FreeBSD documentation team prides itself on high quality and correctness, which is something we try to hammer into contributors. In my personal opinion, bad documentation is no better than being without documentation as it would provide false hopes to those users who wish to make use of it.

George: How difficult has it been to maintain consistency in documentation between FreeBSD DocBook and 5.x, particularly with FreeBSD 5.3 looking to be the breakthrough release in the 5.X family?

Tom Rhodes: It hasn't been too difficult surprisingly; we try to keep up with new features being added while providing information for those not willing to run 5.X yet. Most of the time we provide a note, or even alternative paragraph. In sections which apply only to FreeBSD 5.X, there is usually some introductory statement which mentions that. For an example, I've personally taken the time to document features which are new in 5.X and have always noted that in the beginning paragraphs.

George: Going back to the question of expanding the sections of the Handbook, what is the criteria? For instance, what does it take to add a section on, for example Soekris hardware, which have gained enormous popularity among many *BSD users?

Tom Rhodes: The author must have a good understanding about what they are documenting. It needs to be correct before ever getting placed in the Handbook. New sections must cover all of the basic aspects. Using your example above, I would consider a good section to have at least the following information:

What information will be covered, think of it as a mini-TOC;

What is Soekris and how it is used;

Why use it, perhaps provide a situation where it can be of use;

The configuration of Soekris hardware on FreeBSD (kernel and userland);

Example configurations or situations where the configuration can be applied;

How to work around any or most issues which may arise (troubleshooting).

George: But what would it take for the doc proj staff to consider having a section on Soekris, without others users submitting the documentation?

Tom Rhodes: Time. Most if not all committers are very busy individuals. We all have day jobs or college which require at least a few hours of almost every day. Then we need the hardware; this will give us an opportunity to thoroughly test and play with what we are documenting.

I feel those are minimal requirements.

George: On a more general level, how often do you get direct comments about the Handbook? I for one, have always been amazed at the clarity of *BSD documentation, compared to any other operating system.

Tom Rhodes: From time to time I get a few personal comments, most of them from friends whom I recommended FreeBSD to. I'm sure the other doc committers get personal comments as well. Every so often, I get a comment from someone whom I've never heard of before. This makes me feel good about the work I'm doing, more so when it has helped someone.

George: Tell us about DocBook.

Tom Rhodes: DocBook, sure, what would you like to know? It's the primary mark up language used for the FreeBSD documentation set.

DocBook is interesting, similar to HTML but more enhanced. It provides a basic mark-up language for documentation. The difference between the DocBook you would read about in Norman Walsh's book is minor; the FreeBSD Documentation project has expanded it in such a way where it suits our needs a bit more. Our changes could easily be applied to almost any documentation project. At a first glance, it may be a bit tedious to follow, considering the FDP's conventions, for instance, the way we work with different tags: i.e. manual page entities versus commands, etc.

George: How can an end-user assist the the Handbook without learning DocBook?

Tom Rhodes: We request that all patches to the Handbook and articles be submitted in DocBook.

George: So there's no way to assist the project without knowing DocBook?

Tom Rhodes: Of course, the best way is to look over the FDP Primer, while there is no reason to learn DocBook, it would help us get to the change quicker. If a user does not have the time, then they are welcome to make a post on the mailing list. Every so often a doc committer will have, find, or make the time to convert plain text documentation into DocBook. So while knowing DocBook isn't required, it sure does help during times where we committers are extremely busy.

George: If someone is completely new to the documentation project, and wants to become a committer, what steps do I need to take besides learning DocBook?

Tom Rhodes: First and foremost they should subscribe to our mailing list. This will allow them to watch general conversation so they may pick up on conventions. I would also recommend they review the mdoc(7) manual page as many of us work with manual pages as well. They should then either look over the Problem Reports Database for changes, enhancements, fixes or right out replacements to our current documentation and provide a patch. It is a large task to focus on every change in FreeBSD and then document it and we could always use the help.

George: Recently at USENIX Annual Technical Conference in Boston, I was discussing BSD documentation with Marshall Kirk McKusick, and he attributes its strength to the fact that the Berkeley developers were also central to supporting their own software. How significant do you think that has been to the strength of BSD documentation in general?

Tom Rhodes: Reasonably significant, Dr. McKusick is very correct in his statement. I've noticed that many FreeBSD developers care if people who are using their software have problems; indeed, I have worked with several developers who wanted some documentation written for their code. A few examples are Robert Watson and Poul-Henning Kamp, both whom have worked with me on documentation issues with regards to new code they have added to FreeBSD. It's really important that those who write the code help with the documentation, this reduces any incorrectness between the code and the documentation which in turn helps the users who may want to work with new features provided. This is paramount to the strength of BSD, correct walk-throughs will aid in keeping the level of frustration down when something doesn't work as expected. I know when my frustration level peaks with something, I walk away and every so often I'll look for a better or perhaps completely different solution.

George: Is there a direction that you see the Handbook going in for the future?

Tom Rhodes: While I'm sure you can appreciate the fact that I cannot speak for everyone on the doc project; I would personally like to see the Handbook become the de facto guide to FreeBSD. While the manual pages are great, they are not the place to provide walk-throughs, tutorials or complete instructions for the plethora of tasks which may be handed to FreeBSD.

The Handbook can provide this and I would like to see it eventually cover almost any task which may be performed in the base system as well as more advanced topics like services provided by third party utilities, such as Squid or Apache.

George: That sounds like an area those not directly involved in the documentation project can contribute to.

Tom Rhodes: To an extent, though some software requires a few changes to work properly with FreeBSD over it's intended operating system. For those cases, I feel the documentation project can work well with the developers of third party software packages to provide the best documentation possible.

George: Is there anything else you would like to add, as we conclude this interview?

Tom Rhodes: Yes. Someone once said to me that open source documentation is thankless job where the only time we ever hear from end-users is when something is incorrect. That is not entirely true since I have had positive comments sent to me via email; it would be great to get more end-user review on our work. If something is incorrect then please report it to us, if the Handbook has helped in any significant way then tell us. Our goal is quality, and we can only reach that goal not only by our own hard work but by user feedback.

George: I want to thank you for your time on this Sunday afternoon Tom, and hope that readers of Daemon News gain more appreciation of the work that the documenters do for all the BSD projects.