[Pulp-list] User Guides

[Jay Dobies]

-----BEGIN PGP SIGNED MESSAGE-----
Hash: SHA1

Pulp will be at FUDCON at the end of the month, so I'd really like to
have this in place so we can point the swarm of interested developers to
something easy to follow when they want to start poking around.

I'm thinking we offer two user guides, one for each of our executables.
The outlines below are meant to be the major sections that would go in a
table of contents, with the intention being to skim over and decide "Oh,
this looks cool, let me find out more". The notes that follow are a
quick elaboration of all the parts that the section should cover.

= Pulp Admin User Guide =
* Introduction -- overview on the pulp-admin executable, how it's
different from pulp-client, whether or not you need root to run, what
conf files it uses

* Repositories
** Creation, Removal, Display -- basic CRUD and listing, includes
information on adding a repo's GPG keys, description of what "published"
means
** Synchronization -- includes scheduled syncs, cancelling, foreground syncs
** Packages -- information on adding/removing/uploading packages in
repos; just repo related package stuff here, not the installation or
deplist features
** Errata -- similar to packages, just the repo manipulation, the
installation parts will be covered below under consumers
** Cloning -- more description here of what it means to clone a repo,
how it works in terms of parent/origin/none feeds, what the timeout means
** Distributions -- what they are, where they come from, what you can do
with them

* Consumers
** Removal, Display, History -- also include an overview on what a
consumer is, what key-value information is and how to manipulate it
** Bind -- what it means to bind/unbind a repo, simple overview of
how/when those operations are sent down to the consumer itself
** Package Installation -- simple description of how the installation
request gets to the consumer and how deplist plays into that
** Groups -- describe what it means for a consumer to be part of a
group, reasons for doing so, overview of which operations are available
at the group level but not a complete rewrite of those operations that
have already been discussed in the user guide

* Pulp Users
** Logging in -- simple description of what "auth login" and "auth
logout" do
** User Management -- CRUD on users
** Roles -- CRUD on roles

* Recipes -- Todd mentioned the idea of a cookbook that is loosely tied
to common use cases. I couldn't quite figure out a clean way of doing
the whole user guide like that, but we may want to include some sort of
section that shows common ways of tying together all the coolness. Maybe
we make up a scenario of a fake company and walk through their process
of synchronizing in standard fedora repos, making their own repos and
uploading custom packages, organizing consumers by department, and
applying errata to their client machines (actually, that sounds pretty
damn cool now that I see it all written out -- oh oh, we should get
mizmo to make us some of her stick figures she includes in these sorts
of things).


= Pulp Client User Guide =
* Introduction -- overview on pulp-client, the agent, configuration files

* Creation, Removal -- what it means to "create" a consumer, what
information is required to create a consumer (valid user)

* Consumer Profile -- simple information on what is included in the
consumer's profile and when an updated version is sent to the pulp server

* Repository Bind/Unbind -- what it means to bind, how to list available
repos


I'm not suggesting a War and Peace length novel for each section. I'm
not sure it makes sense to have a standard template, but I'm thinking
some description of what it is that's being done and then some CLI
output from doing it (the current How To is a pretty good model;
bulleted lists of points with some preformatted text following). Some
sections will need a bit more orientation as to what the feature means
(i.e. cloned repos will likely need some explanation as to how they
behave in general and why you'd want to do that).


Thoughts? If I don't hear anything earth shattering by early tomorrow
I'll throw the outline up on the wiki so people can claim ownership and
set up the skeleton on the pulp wiki.

- -- 
Jay Dobies
RHCE# 805008743336126
Freenode: jdob
http://pulpproject.org
-----BEGIN PGP SIGNATURE-----
Version: GnuPG v2.0.14 (GNU/Linux)
Comment: Using GnuPG with Fedora - http://enigmail.mozdev.org/

iQEcBAEBAgAGBQJNJNWEAAoJEOMmcTqOSQHCT4oH/1HjKhOF/bBM3awOOVTkZh6B
9nd2HMhBKwZRhVrg4kzP9PUMop0x50nPtELzjswMtuZGmZ6/zRlMAxrlIzfqBi5b
fQYJl3mQiCCTXasgqN7YoGacc6Q2VdpWrBYKPmm8CnRNQ7O7n33Fa2EFVgTEp7xh
mHDqd98klolV/aFDnmfFgMN9e0MA2ab4pvjSJe5qa1yjbaM84qkZSBuEjlLVPTev
z/xNGFDeEp5FvN/4UVhtrAJyXzU7rqopHlYw3ykGZbIg7WxQyqUPDWTkVb8j7CMZ
txFRYcpIs7gqsvvFuzKNKXP1hY1AGuIVsW+Xl19ob+tpH8NOQDQ2rwevb/vJLm4=
=s+FA
-----END PGP SIGNATURE-----