Archive talk:DocsProject/DocumentationGuide/StyleToDo


 * Adapted and Committed Ideas::

It was suggested in the main page that lines should be removed as they were used in the guide. For archival purposes, I'm going to move them - without revision - over to the discussion page as I introduce each concept into the guide.

Don't overuse "most of," "typically," "usually," "many," and such. 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.

Don't use "You must do X" when "Do X" will suffice.

Run ispell!

Do not say system functions "should" do something. They do or do not, there is no try. ;-)

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 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."

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 to it in your document.

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.

Avoid contractions when possible. They can be confusing to readers for whom English is not a first language.