cobbler documentation
Dan White
ygor at comcast.net
Mon Dec 19 16:17:42 UTC 2011
I am willing to help out.
I have been using Cobbler heavily since June and while I am not (yet) an expert user, I am willing to collaborate my experiences and put some time into the pounding of the necessary wiki pages.
“Sometimes I think the surest sign that intelligent life exists elsewhere in the universe is that none of it has tried to contact us.”
Bill Waterson (Calvin & Hobbes)
----- David Lee <David.Lee at ecmwf.int> wrote:
> 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
> _______________________________________________
> cobbler mailing list
> cobbler at lists.fedorahosted.org
> https://fedorahosted.org/mailman/listinfo/cobbler
More information about the cobbler
mailing list