Yep, I've been thinking about this myself.
I'm pretty much going to move the manage content to the Wiki and make the
manage not much more than a hyperlink.
That way all the documentation is in one place and we don't have multiple
places to maintain things. If it's not on the Wiki, it doesn't exist.
(I've been meaning to ask contributors of a few things to go back in and supply
docs)
This also makes it easy to find things when people are *considering* using the
project, and haven't installed it yet.
I can take care of this one and once moved over we can work on improving things.
--Michael
-- Michael
On Monday, December 19, 2011 at 11:06 AM, David Lee 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] (mailto:[email protected])
> _______________________________________________
> cobbler mailing list
> [email protected] (mailto:[email protected])
> https://fedorahosted.org/mailman/listinfo/cobbler
>
>
_______________________________________________
cobbler mailing list
[email protected]
https://fedorahosted.org/mailman/listinfo/cobbler
