Wiki port of manage docs now up / edit away!

Greg Swift gregswift at gmail.com
Thu Dec 22 15:26:14 UTC 2011


So... when I was redoing the web interface one of the things I had in my
mind was that it would be nice if there was more on the "welcome" page than
just a welcome.  My thought was to have a generic description of the left
hand menu items, but since you are working on this document, it might be
kind of kewl if the simple start here was replicated in the web ui.  Even
if the links just point back to the online documentation?

just a thought.

On Thu, Dec 22, 2011 at 09:18, Michael DeHaan <michael.dehaan at gmail.com>wrote:

> Thanks, totally agree.
>
> I was thinking of breaking things up into subpages.   We might as well
> just make all these pages link directly from User Docs and Start Here may
> eventually go away or just become a subhead.
>
> The Wiki does document cobbler import … and there are examples at the
> bottom in the workflow/example section that can be merged.    Since there's
> a Wiki page on that though, we can just link to it.
>
> Since the workflow for new users is…
>
> 1) edit settings
> 2) cobbler check … and loop until it's mostly clean ...
> 3) cobbler import if at all possible
> 4) now run commands like add/edit/etc
>
> That to me seems to imply pages on the following should exist:
>
> 0)  how we model things (already exists, probably needs cleanup)
> 1)  cobbler settings (what's important?  how do I change things?)
> 2)  running cobbler check (just mentioning the important ones, and there
> are comments in the file, what to do after editing them)
> 3)  cobbler import (already exists)
> 4)  editing objects
> 5)  repository mirroring
>
> Basically makings things more or less task oriented, routing folks through
> reading pages on each of the above in order.   "I know what I want to
> accomplish, now how do I do it, and in what order?"   Rather than burying
> folks under a lot of commands and hoping they run across something they'll
> learn from.
>
> Then there are a few things that probably don't have pages on them, where
> we could take them off the main page too.
>
> *  power management
> *  PXE (boot loop prevention, menu generation, etc)
> *  configuration management (section exists already about puppet, but
> should merge in the built-in config stuff and make easier to understand)
>
> And some pages I think are a bit confusing already exist, but prob need
> cleanup to make more sense:
>
> *  /etc/cobbler/modules.conf
> *  DHCP management
> *  DNS management (particularly hard)
> *  web app security choices
> *  triggers
> *  XMLRPC API (needs lots of examples, probably)
>
> Then there are various things that don't really get documented
>
> * what snippets ship with cobbler and why should you use them
> * etc
>
> Not all stuff we have to do now, of course, but that's sort of my take on
> it.
>
> --Michael
>
>
>
>  On Thursday, December 22, 2011 at 10:00 AM, David Lee wrote:
>
> Michael DeHaaan wrote:
>
> For those that are interested in helping with docs, manage docs are
> now ported over to the Wiki, in a few parts.
>
> https://github.com/cobbler/cobbler/wiki/Start%20Here
>
> This is pretty much most of the manage, which I think should stay more
> or less together. If you split things into too many Wiki pages, it's
> hard to absorb things via osmosis. I would like to mix the examples in
> closer to the job though and incorporate more examples throughout, so if
> you're a new user you don't get bored/confused and wonder what commands
> you actually care about running. [...]
>
>
> Great! Thanks, Michael.
>
> As this is a "Start here" document, it should be simple and clear, and
> avoid unnecessary detail, particular in its opening stages.
>
> I began editing it...
>
> ...but ended up almost completely rewriting the opening sections,
> through to and including the opening paragraphs of "adding
> distributions". The emphasis is on getting a complete beginner started
> with something, anything, and avoiding unnecessary detail.
>
> I haven't really addressed the remainder of the document; my changes in
> the remainder are mostly cosmetic, improving heading/subheading
> structure, etc.
>
> Returning to "adding distributions". While the original man page had
> thoroughly documented "cobbler distro ...", it hadn't (by contrast) got
> a section on "cobbler import ..." at all. So I have begun to structure
> this "adding distributions" sections to cover these related topics. But
> I strongly suspect that most of the options for "distro" also apply to
> "import", so it probably needs further restructuring to clarify this.
>
>
> (By the way, more generally, I'm not yet convinced that every last
> detail of every last option for every last command belongs in a "Start
> here" document...)
>
>
> -- David Lee
> _______________________________________________
> cobbler mailing list
> cobbler at lists.fedorahosted.org
> https://fedorahosted.org/mailman/listinfo/cobbler
>
>
>
> _______________________________________________
> cobbler mailing list
> cobbler at lists.fedorahosted.org
> https://fedorahosted.org/mailman/listinfo/cobbler
>
>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <https://fedorahosted.org/pipermail/cobbler/attachments/20111222/b4cf8803/attachment.html>


More information about the cobbler mailing list