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