[OpenAFS-Doc] bos addhost -clone

[Jeffrey Altman]

This is an OpenPGP/MIME signed message (RFC 2440 and 3156)
--------------enigFBA9AFDF37617EC3D2FF9EC2
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: quoted-printable

On 5/18/2011 12:24 PM, Jeff Blaine wrote:
> http://docs.openafs.org/Reference/8/bos_addhost.html
>=20
>     -clone
>     Register the host given by -host as a non-voting clone
>     site, which prevents the host from becoming a sync-site.
>     This is an advanced feature and should be used with caution.
>=20
> This isn't very helpful information.  I don't know enough
> about it to expand on it, and 5 minutes searching Google
> shows that, as far as I can tell, nobody's ever explained
> it.
>=20
> This is an example of what I consider to be a significant
> problem with OpenAFS releases.

I will review the history of documentation for you.  Back in
the 90s IBM produced some fine documentation in the form of
Quick Start guides, Admin Guides, User Guides, man pages,
etc.  Then prior to the release of OpenAFS 1.0 to the
community, IBM lost the documentation sources.  All that
was intact was the generated HTML output which is nearly
impossible to edit and maintain.

As a side-effect of the inability to update the documentation
all new functionality added to the AFS product after the
documentation was produced was *hidden* from view.  Only
IBM support personnel, the customers the functionality was
developed for, and those with source code licenses knew that
the functionality had been added.

Prior to the release of OpenAFS there were many customer
sites that had source code licenses and which implemented
local modifications to add even more functionality.  Once
OpenAFS was released almost all of this work was folded
into OpenAFS in the first year.  None of this work came with
documentation updates.

It took nearly seven years after the formation of OpenAFS
for a successful conversion of all of the man pages to POD
format and all of the HTML to DocBook so that subsequent
editing could be performed.  In that time nearly ten years
of effort had already been integrated.

Note also that the IBM documentation was available in nearly
a dozen languages.  OpenAFS isn't even trying to support
anything bug English at this point.

> When was this added?  Where is it explained, official
> documentation guides aside, even in some release notes
> for that version?

bos -clone was added on 12 Feb 2001 as part of the
contributions from a source licensee.  You can review
the change in the source tree.

  git show c4a127d0578e521b97131c5dedf9da58f71b0242

> What process do "we" have for blocking releases until
> the documentation is updated to reflect any new options
> or altered behavior?  Why is the documentation considered
> a second or third-class citizen in the release process?
> The development team sure wouldn't make a release with
> half of something coded and enabled.

Most developers working on OpenAFS are paid to do so in
one form or another whether by a commercial support/development
organization or by a host institution that deploys OpenAFS.
I am aware of no one that is paid to write documentation,
or more importantly, update the documentation that was not
written over the missing ten years.

While the gatekeepers can attempt to encourage the submission
of documentation we cannot force it to be written.  When presented
with substantial contributions of new code, the options are
to accept the code as is and attempt to fix it to meet the needs
of the broader community or turn it down.  Inevitably the choice
is made to accept it because having the functionality is better
than not having it.

> The longer that isn't in place, the more skew will grow,
> right?

Absolutely.

> I'm well aware of the volunteer nature involved here,
> am not coming down on anyone, etc.  I get it.  I'm
> part of it.  But let's do something about it, no?

We look forward to seeing documentation patch submissions at
http://gerrit.openafs.org/ from you and anyone else that is willing
to take some time to work on it.  Read the code, take a stab at
writing some text, submit to gerrit, and get feedback from the
community to improve it.

Jeffrey Altman



--------------enigFBA9AFDF37617EC3D2FF9EC2
Content-Type: application/pgp-signature; name="signature.asc"
Content-Description: OpenPGP digital signature
Content-Disposition: attachment; filename="signature.asc"

-----BEGIN PGP SIGNATURE-----
Version: GnuPG v1.4.9 (MingW32)

iQEcBAEBAgAGBQJN1ADLAAoJENxm1CNJffh4cvYH/10zVsSz698oHW2OLmow8Xyp
iReHwCND9vicMFLF9xiJgaK/pHCjKUfo2rMCzAdUMGNMCSbdpKeFYR6eozrTYYk7
RRPgAMTnvZr/+1uxochDfu3ikK1WBG731lOh+9R3CpL6TQq/hZOZr5sRnI37TNrl
akzS4THM9P6Hws9amstGkNZjmkcINAqn7l5SJG/50nQOprbUnku8O+aR0GFAwJw/
ZRnkoqAniWYUHGhWVI1wO4cf9h5lL0tfjb3raic/y9c7zmlsVnYV7kbfcHfOSuT7
ckK3TseJJd+eXbC6VtTTc2OpFZMtUewwpmN7qof4d2icIlxvd00O2UStMe+tSWs=
=gF5h
-----END PGP SIGNATURE-----

--------------enigFBA9AFDF37617EC3D2FF9EC2--