From Fedora Project Wiki

(lines added after commit to guide)
 
m (lines added after commit to guide)
Line 1: Line 1:
::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.
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.


Line 14: Line 16:
Do not say system functions "should" do something. They do or do not,
Do not say system functions "should" do something. They do or do not,
there is no try. ;-)
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."

Revision as of 05:43, 25 October 2011

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