On Sat, 2004-09-04 at 09:04, tuxxer wrote: > Hey guys. > > I'm posting a draft version of what I've got so far of the hardening doc > in my own web-space. It's not much, but it will be updated rather > randomly, as I get chances to work on it. There isn't a "draft" > statement on it at the moment (other than the title), but I'm working on > that, and it will be there shortly. > > > Link: http://members.cox.net/tuxxer/ > > I'll be posting the XML to the bug, once I've finished chapter 1. > > Please feel free to comment, critique, shred, etc. It's good to see you're blazing ahead! I will try and fix up an XML patch for you that will make these points, but I am committing some of them to the list in the hopes they will help others who are lurking and/or working on documents of their own. I will readily admit to being guilty of these same problems from time to time, and I'm marking the suggestions below accordingly. I try to catch the problems before they leave my repo, but as Karsten will testify, that doesn't always happen! I am going to add these issues to my Style TODO as well. 1. Don't overuse "most of," "typically," "usually," "many." These water down your instructions and make the tutorial sound wishy-washy, as if you're trying to CYA. A document the length of a typical tutorial can't possibly cover every single case, and shouldn't try. 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. (Guilty) 2. Don't use first person at all: "I," "me," "my," "mine," "we," "our," "ours." Also do not use "his or her," "his/her," "he or she," "s/he." Reformulate your sentence to eliminate it. 3. Use ispell (or whatever spelling checker you have available) before you post a new version. That simply saves the editor a little time. :-) (Guilty) 4. 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. (GUILTY!) 5. 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... 6. 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. (*** NOTE: I think this brings up an interesting side point, which is that the yum/up2date tutorial currently in process [1] needs some editorial lovin'. Once that's done, any author can point to the finished document at the &FDPDOCS-URL; site. That's what this tutorial should do. ***) 7. Leave out 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. (Guilty) 8. 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.) 9. 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. 10. Avoid contractions when possible. They can be confusing to readers for whom English is not a first language. (Guilty) 11. Avoid slashes "/" in titles or in your prose (except in <filename> or other appropriate context, of course). Use "and" or "or." That's a long list, but not too difficult to learn for your writing. I think these are all minor criticisms, and hope you'll take them in the constructive spirit in which they're offered. Also, visit the following URL's and bring your document in line with their recommendations. Following these guidelines will make your document stronger and more professional looking: http://www.redhat.com/archives/fedora-docs-list/2004-August/msg00307.html http://fedora.redhat.com/participate/documentation-guide/s1-screenshots.html There are others in the archives but I didn't have time to track them all down. They will certainly be collected for the style portion of the Docs Guide as soon as I have time to do that. I'm hoping to start this weekend. = = = = = [1] update-tutorial: https://bugzilla.redhat.com/bugzilla/show_bug.cgi?id=131131 -- Paul W. Frields, RHCE (greedily appropriating Karsten's footnotes)
