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