[Pulp-list] User Guide Conventions

Jay Dobies jason.dobies at redhat.com
Thu Feb 10 15:29:19 UTC 2011


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

Since there are additions being made I wanted to give a few notes on the
conventions used throughout the User Guide in case people aren't
completely familiar with the whole guide. Most of these are a result of
proofreading the permissions section of the guide and I've made changes
where necessary (i.e. correcting all of the typos).


- - The guide isn't the most formal thing in the world, but it is still a
guide and not a chat conversation. Avoid cases where you're talking to
the user:

Instead of:
"You can grant, revoke, and show users permissions on various parts of
the REST API with the `permission` command."

Try:
"Permissions can be granted, revoked, and displayed through the
`permission` command."

It's not supposed to be Shakespeare, but it should be professional.


- - Command arguments are very important; one of the biggest reasons for
the guide that we can provide more details than --help does. Instead of
blowing through the possible arguments in a single run on sentence with
no description of what they are, use a table.

The format used throughout the guide is to note if the arguments are
required or optional and then include a table:

  All arguments are considered required unless otherwise specified:
  || '''Name''' || '''Flag''' || '''Description''' ||
  || Foo || `--foo` || (optional) Does foo. ||

Don't forget to indicate the restrictions on an argument. For instance,
the `permission grant` command accepts `-o` parameters to list the
operations. There is a list in the guide that indicates valid values for
that. Same for repo feed types.

It's not just enumerated values, keep in mind things like numbers and
units too.


- - All CLI snippets are started with $. For example:
$ pulp-admin repo list

This is just a consistency thing to make it appear as a uniform guide
instead of a bunch of disparate sections. It doesn't mean anything other
than the fact that it's what was used throughout the rest of the guide.


- - When talking about a command, use the full path to it. Hierarchically
they may fall under the same section, but don't expect the user to
remember that after scrolling for 2 pages. So instead of:

"The `info` command retrieves..."

Use the full path:

"The `role info` command retrieves..."


- - Typically across the guide we use the term "display" instead of
"show". So something like "Displays details of a user" instead of "Shows
details of a user." This is minor, but I figured I'd point it out.
Personally I'm also a fan of "Retrieves the value of..." instead of
"Gets the value of...".


- - Pulp starts with a capital letter when referring to the project or
product. It starts with a lower case when referring to a command (i.e.
pulp-admin).


- - Proofread! I know some people don't like working in trac directly on
firefox, which is fine. But one benefit of it is that firefox underlines
mispelled words. So when you finally do paste in your changes, take a
glance over it to make sure you haven't spelled anything incorrectly
before hitting submit. It's just embarrassing to have 10 typos on a
single page. It'll take like 2 minutes, I promise.

- -- 
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/

iQEcBAEBAgAGBQJNVARPAAoJEOMmcTqOSQHC1fEH/iqj9KgjhqVHiAjJiXGeDd1B
Nw3gFWsMEcsn95ONGBhFrwZX4fs+8QY88xCU+HpoSNB6OZvG3qojn4Db6fd8XodN
tMbN59pYQ75HLMOX9Ph244kh5N+8uwLCIKv8TC9tzV2ucuGRzabPtnzQ6ryK/1ic
ZCDpcgxVW7vgdSp8HnV2HdE34j/MN7MN9b3FOv2GDzw2u5atLiGGzO/Id1jd9e7n
nDGgXfGU0hMMxAoqwr44tYL7XLaN8Zz2aire1FCXIMv1tFw/uDrxIwiRQ+f/k+PJ
mUiCG0rTU+aD8XzBbGb4/JtQhwQHWaNG01hgLTQwuaRn3ABLI9pOyNM/JYKfujI=
=YW7S
-----END PGP SIGNATURE-----




More information about the Pulp-list mailing list