Archive:Docs Project Style Guide - Introduction to Style

From FedoraProject

(Difference between revisions)
Jump to: navigation, search
m (Writing is generally used as a verb in this paragraph, better to use a clear noun like documentation or content to aid in translation efforts. Tightened up last sentence so it sticks.)
m (provides was an awkward verb for an inanimate style guide, it is more of an outline, and used independent clause to make the last sentence mroe clear. Easy-to-read was in the paragraph twice.)
Line 5: Line 5:
 
Writing high-quality documents easily understood by multiple readers is a difficult challenge.  There are many different techniques that can be used in writing, and there are many different ways of writing the same information.  In order to provide consistent, readable documentation, certain standards must be established.  There are many different writing style guides that serve different purposes and audiences.  Good style is something learned and practiced.
 
Writing high-quality documents easily understood by multiple readers is a difficult challenge.  There are many different techniques that can be used in writing, and there are many different ways of writing the same information.  In order to provide consistent, readable documentation, certain standards must be established.  There are many different writing style guides that serve different purposes and audiences.  Good style is something learned and practiced.
  
The Fedora Documentation Project is tasked with producing friendly, easy-to-read documentation for a worldwide audience.  This means writing clean, clear documents with a great deal of attention to differences in cultures and languages.  The Fedora Documentation Style Guide provides specific rules and recommendations to consistently produce documentation that can provide both technical and non-technical information in a way that is easy to read and understand.
+
The Fedora Documentation Project is tasked with producing friendly, easy-to-read documentation for a worldwide audience.  This means writing clean, clear documents with great attention to differences in cultures and languages.  The Fedora Documentation Style Guide outlines specific rules and recommendations for documentation contributors, standardizing documentation of both technical and non-technical information, to increase readability and comprehension.
  
 
The writers producing this documentation come from a variety of backgrounds and possess a variety of different skill sets.  Through these rules and guidelines, they can produce and collaborate on documentation with consistent results.  This style guide may vary from what each writer or editor is familiar with, but practicing this guide will eventually provide them with a comfortable standard that may provide benefits outside of Fedora's documentation.  This style guide will itself demonstrate the rules and guidelines it provides.
 
The writers producing this documentation come from a variety of backgrounds and possess a variety of different skill sets.  Through these rules and guidelines, they can produce and collaborate on documentation with consistent results.  This style guide may vary from what each writer or editor is familiar with, but practicing this guide will eventually provide them with a comfortable standard that may provide benefits outside of Fedora's documentation.  This style guide will itself demonstrate the rules and guidelines it provides.
  
 
This style guide borrows many ideas from the Associated Press (AP) Stylebook and The Chicago Manual of Style. It contains many differences from those guides that are intended to enhance the value of these documents for international readers and to better accommodate the technical nature of the Fedora documentation.  In particular, this style guide adopts international standards for many common notations to avoid confusion among the different cultures that may benefit from Fedora's documentation.
 
This style guide borrows many ideas from the Associated Press (AP) Stylebook and The Chicago Manual of Style. It contains many differences from those guides that are intended to enhance the value of these documents for international readers and to better accommodate the technical nature of the Fedora documentation.  In particular, this style guide adopts international standards for many common notations to avoid confusion among the different cultures that may benefit from Fedora's documentation.

Revision as of 20:08, 18 September 2008

DocsProject Header docTeam1.png


Introduction to Style

Writing high-quality documents easily understood by multiple readers is a difficult challenge. There are many different techniques that can be used in writing, and there are many different ways of writing the same information. In order to provide consistent, readable documentation, certain standards must be established. There are many different writing style guides that serve different purposes and audiences. Good style is something learned and practiced.

The Fedora Documentation Project is tasked with producing friendly, easy-to-read documentation for a worldwide audience. This means writing clean, clear documents with great attention to differences in cultures and languages. The Fedora Documentation Style Guide outlines specific rules and recommendations for documentation contributors, standardizing documentation of both technical and non-technical information, to increase readability and comprehension.

The writers producing this documentation come from a variety of backgrounds and possess a variety of different skill sets. Through these rules and guidelines, they can produce and collaborate on documentation with consistent results. This style guide may vary from what each writer or editor is familiar with, but practicing this guide will eventually provide them with a comfortable standard that may provide benefits outside of Fedora's documentation. This style guide will itself demonstrate the rules and guidelines it provides.

This style guide borrows many ideas from the Associated Press (AP) Stylebook and The Chicago Manual of Style. It contains many differences from those guides that are intended to enhance the value of these documents for international readers and to better accommodate the technical nature of the Fedora documentation. In particular, this style guide adopts international standards for many common notations to avoid confusion among the different cultures that may benefit from Fedora's documentation.