cobbler documentation

David Lee David.Lee at ecmwf.int
Mon Dec 19 16:06:27 UTC 2011


I'd like to suggest that we review, for the long term, the aims and 
objectives of the cobbler documentation and how it should be structured 
to meet them.

We currently have a huge man page, whose structure is inconsistent with 
the usual structure of UN*X man pages.  (As one trivial example the 
section "See Also" would normally be at the end, but we have it half-way 
down the first page of a 17-page (troff-style) document.)

The man page also tries to serve multiple purposes, with:
  (a) a lot of reference-like detail
  (b) several examples of cookboook/workflow
  (c) several "advanced topics", but no apparent pattern.

We also have the wiki (recently moved from fedorahosted to github) which 
seems to have lots of very useful user-oriented information on 
particular topics, with cookbook and workflow items.

We could discuss the details of any of those.  But I suggest that, for 
the moment, we concentrate on the bigger picture, avoiding detail except 
by way of example.

Usually in UN*X documentation, small topics such as the "cat" command 
use the man page mainly reference information about the details, and 
have sufficient examples to cover cookbook and workflow purposes.  The 
topic is small enough for the "man" page to be all-purpose.

Big topics ("make", "rcs", "pam" etc.) tend to limit the man page to 
reference information about command options.  Separately from the man 
page, the fuller information, such as user guides and substantial 
examples, is in other, non-man, documentation.  These big topics 
generally avoid overloading their man page.

One other make-like technique sometimes used for big topics is to have 
related man pages, not necessarily directly connected to particular 
commands.  For instance "rcs" also has an "rcsintro" man page (but no 
"rcsintro" command).  Going further, the "PAM" subsystem has a man page 
for each PAM module, even though there are no PAM commands (including 
"pam" itself).

 From this information perspective, Cobbler must surely classify as a 
big topic (like "make") rather than a small topic (like "cat").

So I'd like to suggest that we review the structure of Cobbler 
documentation.

Whatever happens, it can be argued that the man page called "cobbler" 
should end up considerably smaller, providing a summary and outline of 
what cobbler does, but avoiding the geek temptation to include every 
last detail of every last advanced topic.

The details of particular subcommands ("distro", "system", etc.) could 
be farmed out to additional man pages, perhaps called "cobbler-distro", 
  etc.  But these, too, should probably avoid the "include every last 
detail" temptation.

To complement this, in these days of Internet connectivity being normal, 
we can make full use of the wiki, suitably and liberally referenced from 
the man page.  While the main "cobbler" man page could perhaps give some 
deliberately simple "workflow" examples, we should probably make much 
fuller use of the wiki for providing fuller examples of this nature. 
Almost certainly the wiki, not the man page, should be the prime 
repository for "advanced topics".

I realise that Cobbler, like much open source software, is supported by 
volunteer effort, so that time and effort are severely limited.  That's 
why my suggestions above stay with the existing technology and 
documentation structures.  It is also why I haven't suggested anything 
totally different, such as a writing a reference manual (as is the case 
with, for instance, "make") as that would be a major effort.

Thoughts?


-- 
: David Lee
: ECMWF (Data Handling System)
: Shinfield Park
: Reading  RG2 9AX
: Berkshire
:
: tel:    +44-118-9499 362
: email:  david.lee at ecmwf.int


More information about the cobbler mailing list