[OpenAFS-Doc] bos addhost -clone

[Michael Meffie]

Jeff Blaine wrote:
> http://docs.openafs.org/Reference/8/bos_addhost.html
> 
>      -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.
> 
> 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.
> 
> This is an example of what I consider to be a significant
> problem with OpenAFS releases.
> 
> When was this added?  Where is it explained, official
> documentation guides aside, even in some release notes
> for that version?
> 
> 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.
> 
> The longer that isn't in place, the more skew will grow,
> right?
> 
> 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?

I don't consider this particular example to be a problem with the
software releases.  In my opinion OpenAFS does have decent
documentation, compared to may open source projects, thanks to the
efforts of many people and the inherited documentation from IBM.

Man pages are necessarily terse, being reference documentation.  I would
say the admin guide, or something new, needs to explain the details of
how AFS database replication works, to the level of detail useful for
system administration.

Mike --