Questions regarding documentation

[Simon Lyngshede <simon-sunsite_(_at_)_s-et_(_dot_)_aau_(_dot_)_dk>]

We're currently working on an article on the subject of hiring new
developers in software companies. One of the issues we're trying to
address is that of documentation, as the companies we're working with,
to a large extent are ignoring this. To help these, and other
companies, to a better documentation process, we looking a various
open source projects, in an attempt to find methods or common
practises that might help.

In a previous article, on software quality, we asked a few questions
here on the misc list, and got some really good and useful answers, we
hope that the developers once more will be able to spare a few minuets
of their time. 

We have been observing OpenBSD cvs logs for around six months and is
very impressed by how much work the OpenBSD developers put into
writing documentation, and keeping it up to date. Especially the work
on the man pages has caught our attention. There are however a few
questions we hope the developers wouldn't mind answering.

- It has been observed that patches have been removed, due to lack of
  documentation. Is this common practise, or simply rare exceptions?

- How are developers being motivated to document their changes,
  i.e. keep the manual page synchronised with the actual code?

- Does rules exist, which inform developers on what to document, if
  not, how do developers know what to document?

- The OpenBSD developers have written a series of smaller applications
  over the past year (OpenNTPD, OpenBGPD, hostapd...), are the design
  of these documented, if so, are this documentation made available to
  the other developers?


Thank for your time.

-- 
Regards 
Simon Lyngshede
David Sxndergaard
Aalborg University, Denmark