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: [email protected]
_______________________________________________
cobbler mailing list
[email protected]
https://fedorahosted.org/mailman/listinfo/cobbler
