-----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----- _______________________________________________ Pulp-list mailing list [email protected] https://www.redhat.com/mailman/listinfo/pulp-list
