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.


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@lists.fedorahosted.org
https://fedorahosted.org/mailman/listinfo/cobbler