These are notes for the Style chapter in the Documentation Guide . Remove each from the list when it is committed to the chapter in CVS.
Tips
Using <replaceable> -- if you formally state something will be used as a convention, don't use <replaceable> in the text.
Don't overuse admonitions. Anything that is in the admonition which can be moved outside, should be moved outside.
Do not say system functions "should" do something. They do or do not, there is no try. ;-)
Don't use first person "I," "we" or "us" to refer to yourself the writer (with or without the reader), nor third person singular in docs to refer to users. It's not a conversation, it's technical documentation. Using "you" to refer to the reader is fine, especially when giving instructions. Using "you" is MUCH preferred to the gender-specific "he" or "she," the awkward "he or she," the ugly "s/he," and the excessively dry "one."
Your tips should adequately cover a stock installation of Fedora Core, in the present version. Don't state this beyond the context of your document's goal(s); the fact that it's going to be an official Fedora Doc makes this the case.
Use active voice. "Issue this command," not "The XXX command needs to be run." The tutorial tells the user how to do something, and should give instructions clearly and concisely.
Don't use abbreviations like FC2 or FC. Instead, use the entity &FC; (which inserts the words "Fedora Core" thanks to our entities) with or without &FCVER; (the version number). Put a space between &FC; and &FCVER; like this:
&FC; &FCVER; provides firewall capabilities...
This is a matter of content: Don't cover updates (up2date or yum) in a tutorial about system hardening, beyond stating the user should pull system updates. Direct the reader to other resources. If every tutorial author does this, the aggregate wasted time will be substantial. There may not be an "official" update-tutorial to link to right now, but that's fine. Simply leave a place marker; there's a tutorial on the way for that subject. When it shows up, add a <ulink> to it in your document.
Avoid statements like "One of the most important things to do is to mind your P's and Q's." If it's important, the reader expects it to be in your tutorial. The converse is also true: if it's in your tutorial, the reader expects it is important, especially if you use a whole section for it. Merely state, "Mind your P's and Q's." Then elaborate as required. If the whole section concerns how to mind one's P's and Q's, you may be able to leave this sentence out entirely.
When you direct readers, use correct words for the actions they should take. Users do not "go to" the Main Menu -> Foobar. They either click on Main Menu and then click on Foobar, or from the Main Menu they select Foobar. (I would argue the latter is better, because some people don't use a mouse even in the GUI. I actually avoid it depending on what I'm doing at the time.)
Avoid punctuation in your titles for sections or admonitions -- except for commas where demanded. ("Important!:", "Note:".) Instead, just use the title itself ("Important"). It is helpful (and encouraged) to use a title that says something about the admonition comment, such as "Stop services." This is a minor style point, but your editor will likely fix it if you don't.
Avoid contractions when possible. They can be confusing to readers for whom English is not a first language.
Avoid slashes "/" in titles or in your prose (except in <filename> or other appropriate context, of course). Use "and" or "or."
The word "will" (future tense) is almost never needed. Rewrite in present tense unless future tense is actually required for the sentence to make any sense.
Following an "if" clause, use a comma to separate the dependent clause instead of the word "then." (The word "then" is great for programming, but completely unnecessary in written English.) "If the build fails, check the output for possible causes."