[documentation-guide: 1/2] Adding more style guide goodness
Eric Christensen
sparks at fedoraproject.org
Sat Mar 22 04:40:05 UTC 2014
commit 7c3acef8daab11a45706f3636a0eda855164b2ef
Author: Eric Christensen <echriste at redhat.com>
Date: Sat Mar 22 00:39:28 2014 -0400
Adding more style guide goodness
en-US/style.xml | 1070 +++++++++++++++++++++++++++++++++++++++++++++++++++++++
1 files changed, 1070 insertions(+), 0 deletions(-)
---
diff --git a/en-US/style.xml b/en-US/style.xml
index 10591f1..d203208 100644
--- a/en-US/style.xml
+++ b/en-US/style.xml
@@ -155,4 +155,1074 @@
<para>The overall goal of the Fedora Documentation Project is to provide assistance to Fedora users in easy-to-understand language. You do not have to write to impress an English professor, or show off your expertise in a subject matter. Short sentences, frequent definitions of new and unfamiliar terms, and reference links are all aids our audience appreciates most. Write with your target audience in mind, and it will be your documentation contributions with the highest visits of users in need of answers.The following sections provide guidelines for both sentence composition and syntax usage. Follow these guidelines to ensure your document's tone is consistent with that of other Fedora documentation.</para>
</section>
</section>
+ <section id="sect-documentation_guide-style-content_and_rendering">
+ <title>Content and Rendering</title>
+ <para>Writing documentation for display on assorted media through various technologies presents unique requirements. In general, keep the written content and rendering information separate. Rendering information is the formatting markup language to distinguish types of information, such as bold text to add emphasis. Modern technologies empower writers to use specialized markup language to enhance communication. It is imperative writers participating in collaborative projects like the Fedora Documentation Project adhere to standards and prescribed templates.</para>
+ <note><title>Benefits of Content and Markup Language Separation</title><para>Keeping content material and markup language separate from each other within documentation adds an additional benefit. As new media formats develop, project coordinators easily remove markup language and re-format the original content for the new communication outlet. Therefore, separating markup language from subject matter content encourages use of the original content for future projects with little additional effort.</para></note>
+ </section>
+ <section id="sect-documentation_guide-style-dates_and_times">
+ <title>Dates and Times</title>
+ <para>The styles used for dates and times vary widely around the world, and this creates a lot of confusion. While there is consensus on one calendar for most business purposes, the dates on this calendar can be represented in many different ways. The varying uses of daylight saving time and assorted ways of representing time can make even simple communications more difficult. International standards have been developed to effectively communicate dates and times, and these standards should be used for publications that may reach a global audience.</para>
+ <section id="sect-documentation_guide-style-dates_and_times-absolute_dates_and_times">
+ <title>Absolute Dates and Times</title>
+ <para>Absolute dates and times specify specific points in time and may include points in the past, present, or future.</para>
+ <para>The ISO 8601 standard provides a simple way to represent dates and times that is easily recognized around the world and is equally easy to use. Under this standard, all values are ordered from most to least significant. Write all absolute dates and times in accordance with the ISO 8601 standard.</para>
+ <section id="sect-documentation_guide-style-dates_and_times-absolute_dates_and_times-absolute_dates">
+ <title>Absolute Dates</title>
+ <para>Absolute dates are written with the four-digit year first, the two-digit month second, and the two-digit day last. Each value is separated with a hyphen. This format is written as "<code>YYYY-MM-DD</code>".</para>
+ </section>
+ <section id="sect-documentation_guide-style-dates_and_times-absolute_dates_and_times-absolute_times">
+ <title>Absolute Times</title>
+ <para>Absolute times are written with the two-digit hour first and the two-digit minute second. Each value is separated by a colon. This format is written as "<code>HH:MM</code>".</para>
+ <para>Additional precision is provided using seconds. Seconds are written as two-digit integers. Minutes and seconds are separated by a colon. This format is written as "<code>HH:MM:SS</code>".</para>
+ <para>Any fraction of a second is written as a decimal number. No limit is placed on the precision used. For example, to use precision of 1/100th of one second, this format is written as "<code>HH:MM:SS.NN</code>".</para>
+ <para>Absolute times are followed by a timezone specification. The Coordinated Universal Time (UTC) is a universally recognized time standard and is preferred for absolute time specifications. This is sometimes referred to as Greenwich Mean Time (GMT) or Zulu Time (Z). The preferred way to specify a time in UTC is to follow the time with a space and "UTC". This format is written as "<code>HH:MM UTC</code>".</para>
+ </section>
+ </section>
+
+ </section>
+ <section id="sect-documentation_guide-style-fedora_specific">
+ <title>Fedora Specific Conventions</title>
+ <para>The Fedora Project uses specific conventions that extend beyond the general style rules and guidelines. These conventions exist to produce specific results from the toolchains or to better address the specific requirements of the Fedora Project.</para>
+ <section id="sect-documentation_guide-style-fedora_specific-screenshots_and_images">
+ <title>Screenshots and Images</title>
+ <para>Images and especially screenshots are hard to maintain, hard to translate, and have to be changed constantly with every test.</para>
+ <para>Screenshots do not give any more information than is already given with the text. The user is most often following along with the instructions, so the screen is up in front of them already.</para>
+ <para>Many people perceive that screenshots are necessary in help documents, often because they've seen other documents use screenshots. Avoid this trap. Screenshots lower the quality of the document by taking up valuable space with repetitive imagery and distracting authors from maintaining the far more valuable content.</para>
+ <para>Diagrams are different from screenshots. A diagram is a graphic that is self-descriptive and in many cases can be very useful or show things that cannot be described as well with words. In such cases it is worth the extra effort to maintain the graphic, including dealing with localization. Fortunately, most documents do not need more than one or two diagrams.</para>
+ </section>
+ <section id="sect-documentation_guide-style-fedora_specific-general_conventions">
+ <title>General Conventions</title>
+ <para/>
+ <section id="sect-documentation_guide-style-fedora_specific-general_conventions-software_management">
+ <title>Software Management</title>
+ <para>Software that appears in any official Fedora documentation must adhere to these guidelines:
+ <simplelist>
+ <member>Software must be available in the official Fedora software repositories for the release of Fedora to which the documentation applies.</member>
+ <member>Software installation must be done via Fedora software management tools, preferably <code>yum</code>. If you document using GUI tools for package installation and management, cover the default application (<code>pirut</code>) before others, and cover it consistently.</member>
+ <member>Software must not require user compilation from source, or rebuilding from source RPMs.</member>
+ <member>Guides must not encourage reconfiguration of file system resources, security contexts, or any other resources from a software package that conflict with the intention of the maintainer for that software package.</member>
+ </simplelist></para>
+ </section>
+ <section id="sect-documentation_guide-style-fedora_specific-general_conventions-administration_tools">
+ <title>Administration Tools</title>
+ <para>Guides must use the following conventions for system administration:
+ <simplelist>
+ <member>Neither assume, nor configure, <code>sudo</code> rights. Use the following command instead:<command>su -c "<COMMAND>"</command></member>
+ <member>To configure the current or persistent activation of services through initscripts, use the <code>/sbin/chkconfig</code> and <code>/sbin/service</code> binaries.</member>
+ </simplelist></para>
+ </section>
+ </section>
+ <section id="sect-documentation_guide-style-fedora_specific-DocBook_XML">
+ <title>DocBook XML</title>
+ <para>The preferred format for long-term maintenance of documents is DocBook XML. This format stores contextual style information without concern for document rendering and avoids common limitations of other document storage formats.</para>
+ </section>
+ <section id="sect-documentation_guide-style-fedora_specific-wiki">
+ <title>Wiki</title>
+ <para>Wiki markup is a structured form of plain text that is not as complex as DocBook XML and has become a popular format for new writing. The wiki format and the limited available markup are simple. Wiki is easy to read and edit in normal plain text editors. Unfortunately, it lacks the contextual markup that DocBook XML provides. The Fedora Project has adopted specific conventions to provide basic contextual support in the wiki format.</para>
+ </section>
+ <section id="sect-documentation_guide-style-fedora_specific-ReST">
+ <title>ReST</title>
+ <para>ReST is a lightweight structure form of plain text that can be used to produce meaningful XML output.</para>
+ </section>
+ <section id="sect-documentation_guide-style-fedora_specific-plain_text">
+ <title>Plain Text</title>
+ <para>Plain text documents contain no markup for style or context. They also lack any inherent structure. Original writing in plain text generally requires revision, including the addition of markup, before publication. A plain text document that uses wiki conventions and markup is easier to translate into wiki format, and using those conventions can improve the readability and structure of the document.</para>
+ </section>
+ <section id="sect-documentation_guide-style-fedora_specific-other_formats">
+ <title>Other Formats</title>
+ <para>There are many other formats for text storage. Each may provide different features and drawbacks. If a specific structure is adhered to, the amount of effort required to convert documents between different formats can be minimized.</para>
+ </section>
+ </section>
+ <section id="sect-documentation_guide-style-common_mistakes">
+ <title>Common Mistakes</title>
+ <para>Writers, even experienced ones, frequently make some simple mistakes. Once writers develop correct usage into habits, they can avoid these mistakes.</para>
+ <section id="sect-documentation_guide-style-common_mistakes-spelling">
+ <title>Spelling</title>
+ <para>The following words appear in texts frequently and are often spelled incorrectly. This list does not include locale-specific differences in spelling.
+ <simplelist>
+ <member>INCORRECT: dependant, dependancies</member>
+ <member>CORRECT: dependent, dependencies</member>
+ </simplelist>
+ <simplelist>
+ <member>INCORRECT: kernal</member>
+ <member>CORRECT: kernel</member>
+ </simplelist>
+ <simplelist>
+ <member>INCORRECT: seperate</member>
+ <member>CORRECT: separate</member>
+ </simplelist>
+ </para>
+ </section>
+ <section id="sect-documentation_guide-style-common_mistakes-grammar">
+ <title>Grammar</title>
+ <para><emphasis>A v. an</emphasis> - The choice of which article to use, 'a' or 'an', is made by the sound of the first letter of the word following the article. The 'a' is used when the initial sound is a consonant, the 'an' is used when the initial sound is a vowel. The word 'SSH' starts with the "ess" sound, so the 'an' is used.</para>
+ <para>One common confusion is with acronyms and abbreviations, because that can change how you pronounce something. For example, if 'URL' is pronounced "You arr ell," it is "a URL". If 'URL' is pronounced "Earl" ("Urrl"), it is "an URL."</para>
+ <para>References: <ulink url="http://www.drgrammar.org/faqs/#36 and http://grammar.ccc.commnet.edu/GRAMMAR/abbreviations.htm" /></para>
+ </section>
+ <section id="sect-documentation_guide-style-common_mistakes-punctuation">
+ <title>Punctuation</title>
+ <para>Sentences using "which" or "that" to separate statements frequently contain mistakes in the usage of commas. An instance of "which" is preceded by a comma, which is often forgotten. Instances of "that" are often incorrectly preceded by a comma that should not be present. When in doubt, trust your ear. "Which" wants a pause before it and "that" does not.</para>
+ <para>Use a comma for serial lists before the last item, that is:
+<literallayout>
+"Foo, bar, and baz."
+
+... not ...
+
+"Foo, bar and baz."
+</literallayout>
+</para>
+ <para>Without the final comma, it is hard to tell if the final item is a "bar" or a "bar and baz". (Writers and editors sometimes refer to this punctuation as a "Harvard comma" or "serial comma.")</para>
+ </section>
+ <section id="sect-documentation_guide-style-common_mistakes-contractions">
+ <title>Constractions</title>
+ <para>Avoid contractions in professional writing. They are rarely needed or desired, and they are a common source of errors. When using them, writers often make errors that include spelling, placement of apostrophes, and improper usage within a sentence. The first rule to remember about contractions is that the apostrophe should be placed where the last omission of letters occurs.</para>
+ </section>
+ </section>
+ <section id="sect-documentation_guide-style-word_usage">
+ <title>Word usage, capitalization, and spelling</title>
+ <para/>
+<!--
+'''%'''
+See percent.
+
+
+'''24x7'''
+See also ''time''.
+
+
+'''3-D''' (n. or adj.)
+
+
+'''a.m.'''
+Lowercase with periods and a preceding space.
+
+
+'''above'''
+Do not use to refer to information mentioned previously. When documents are converted to another format or layout, the information may no longer be “above.”
+
+'''acronyms'''
+Spell out acronyms or initialization before using them in text, e.g., “Embedded DevKit (EDK).” Unless the acronym or initials stand for a proper noun, use sentence case for the spelled-out version, e.g., “central processing unit (CPU).”
+
+To form the plural of an acronym, add a trailing, lowercase s with no apostrophe, e.g., ROMs, PINs.
+
+'''affect'''
+When you affect something, it produces an effect.
+
+'''alpha release'''
+Do not capitalize this, as in "the alpha release of Product Foo."
+
+'''alternate'''
+Do not use this to mean “an alternative to something.” “Alternate” is a verb that means to change between two states or options. As an adjective, it means every second (alternating) thing in a series. If you mean “another way or option,” use “alternative.”
+
+'''and/or'''
+Avoid if possible. One or the other nearly always conveys the real meaning. If it doesn’t, try a structure like, “Have some bacon, eggs, or both.”
+
+'''applications'''
+When used as a proper name, use the capitalization of the product or project, such as GNUPro, Source-Navigator, and Red Hat Enterprise Linux. When used as a command, use lowercase as appropriate, such as “To start GCC, type gcc.”
+
+''Note: “vi” is always lowercase.''
+
+'''assure'''
+Assure suggests mental comfort. Example: “I assured my future father-in-law that I would eventually find a job.” Also see ensure and insure.
+
+'''auto-detect'''
+
+'''Autofs'''
+
+'''backport'''
+
+'''back end''' (n.); '''back-end''' (adj.)
+
+'''back up''' (v.); '''backup''' (n.); '''back-up''' (adj.)
+
+'''backtrace'''
+
+'''backward'''
+Avoid using “backwards” unless you are stating that something has “backwards compatibility.”
+
+'''backwards compatibility'''
+
+'''bandwidth'''
+
+'''basically'''
+Do not use. For example, removing the word “basically” in the following sentence strengthens it: “This is how it is basically done.”
+
+'''because'''
+Do not use “since” to mean “because.” Use “because” to refer to a reason. Use “since” to refer to the passage of time.
+
+'''below'''
+Do not use to refer to information mentioned “below.” When documents are converted to another format or layout, the information may no longer be “below.”
+
+'''BIOS'''
+Plural: BIOSes
+
+'''big data'''
+Descriptive term, not a proper noun, so not capitalized.
+
+'''bit rate'''
+
+'''Boolean'''
+
+'''boot disk'''
+
+'''boot loader'''
+
+'''Bps, bps'''
+Bits per second is abbreviated bps. Bytes per second is abbreviated Bps. Also see bandwidth.
+
+'''Britain'''
+The language is English, and the place is the United Kingdom of Great Britain and Northern Ireland, aka the UK. Using Britain/British is usually wrong and to some implies a specific subjective statement about the state of Northern Ireland.
+
+'''bug fix'''
+
+'''built-in'''
+
+'''bulleted lists'''
+Lists should always consist of more than two items. Use bullets for a list in which the order of items is unimportant. Use a numbered list only when the order is important, as in a series of steps.
+
+'''can/may'''
+Use “can” to describe actions or conditions that are possible. Use “may” only to describe situations where permission is being given.
+
+'''cannot'''
+
+'''canceled'''
+
+'''capitalization'''
+If it’s not the official name of a real product or service, don’t capitalize it. Not even if it seems important. Capitalize only the first letter of the first word in headlines, titles, subtitles, and other call-out text.
+
+'''cd or CD'''
+When referring to the change directory command, use cd. When referring to a compact disk, use “CD.” The plural is “CDs.”
+
+'''checkbox'''
+
+'''chipset'''
+
+'''ciphertext'''
+
+'''client side''' (n.); '''client-side''' (adj.)
+
+'''cloud'''
+Use a lowercase “c” when referring to cloud or cloud computing in a general sense.
+
+'''combo-box'''
+
+'''commas'''
+Use serial commas. A serial comma is the comma before the “and” in a series of three or more items: “Item 1, item 2, and item 3.” Because in some cases it is necessary to use a serial comma to avoid confusion, it is best to always use it for consistency. An exception to this rule is in press releases, where it is traditional and preferred not to use serial commas.
+
+'''comma-delimited''' (adj.)
+
+'''command-driven''' (adj.)
+
+'''command language, line, processor'''
+
+'''contractions'''
+Avoid when writing policy manuals or other more formal types of manuals. Contractions may also cause problems for documents that are translated, so avoid them in global content.
+
+'''control character'''
+
+'''control key'''
+Use Ctrl instead, such as “To save the program, press Ctrl+Z.”
+
+'''control program'''
+
+'''cross-site scripting'''
+
+'''cross-platform'''
+
+'''currency'''
+Use the following format: $1,500 USD, omitting “USD” if it is clear that it is in US currency.
+
+'''daisy chain'''
+
+'''dashes'''
+When possible, use em-dashes (—) with no space on either side. When full em-dashes aren’t available, use double-dashes with no spaces on either side--like this.
+
+'''datacenter'''
+
+'''data mirroring'''
+
+'''data type'''
+
+'''datasheet'''
+
+'''debug'''
+
+'''denial of service (DoS)'''
+
+'''dialog box'''
+
+'''different'''
+Use “different from” rather than “different than.”
+
+'''disc, disk'''
+Compact disc, but diskette or hard disk.
+
+'''double-click'''
+
+'''downtime'''
+The period during which a server, service, or other resource is unavailable.
+
+'''download'''
+
+'''dual-boot'''
+
+'''DVD writer'''
+Do not use DVD burner or CD burner (use CD writer in that case).
+
+'''e-book, e-business, e-commerce, e-learning'''
+
+'''earlier'''
+''See later.''
+
+'''Emacs'''
+
+'''email'''
+
+'''effect'''
+''See affect.''
+
+'''email'''
+
+'''ensure'''
+Ensure means “to make sure.” ''Also see assure and insure.''
+
+'''essentially''
+Do not use. ''Also see basically.''
+
+'''Ethernet'''
+
+'''exclamation points (!)'''
+Do not use them at the end of sentences. An exclamation point can be used when referring to a command, such as the bang (!) command.
+
+'''Exif'''
+
+'''ext3'''
+
+'''extranet'''
+
+'''failover''' (n.); '''fail over''' (v.)
+
+'''fault tolerance'''
+
+'''Fedora™ Project'''
+
+'''fiber'''
+Despite the alternative spelling used in Fibre Channel, “fiber” is the correct form to use in all other cases.
+
+'''Fibre Channel'''
+
+'''file name'''
+
+'''file system'''
+
+'''FireWire'''
+
+'''firmware'''
+
+'''floating point'''
+
+'''forward'''
+Avoid using “forwards.”
+
+'''front end''' (n.); '''front-end''' (adj.)
+
+'''FTP'''
+Stands for file transfer protocol. You may actually need to refer to SFTP, secure file transfer protocol. Use lowercase when referring to the command-line program.
+
+'''g++''' or '''G++'''
+When referring to the command, use g++. When referring to the program, use G++.
+
+'''gas''' or '''GAS'''
+When referring to the command, use gas. When referring to the program, use GAS.
+
+'''GB'''
+
+'''Gbps'''
+
+'''gcc or GCC'''
+When referring to the command, use gcc. When referring to the program, use GCC.
+
+'''gcj or GCJ'''
+When referring to the command, use gcj. When referring to the program, use GCJ.
+
+'''gdb or GDB'''
+When referring to the command, use gdb. When referring to the program, use GDB.
+
+'''gigabyte'''
+2 to the 30th power (1,073,741,824) bytes. One gigabyte is equal to 1,024 megabytes. Abbreviated “GB.”
+
+'''GIMP (GNU Image Manipulation Program)'''
+
+'''GNOME'''
+
+'''GNU'''
+(GNU’s Not UNIX)
+
+'''GNUPro'''
+
+'''gray'''
+
+'''GTK+'''
+
+'''hard-coded''' (adj.); '''hard code''' (v.)
+
+'''hard copy'''
+Do not use. Instead, use “printed.”
+
+'''hard disk'''
+
+'''hard drive'''
+
+'''he/she'''
+Do not use. Reword to avoid.
+
+'''high-availability''' (adj.); '''high availability''' (n.)
+
+'''high-performance computing (HPC)'''
+
+'''homepage'''
+
+'''host group'''
+
+'''hostname'''
+Capitalize when used at the beginning of a sentence, but try to reword the sentence to avoid this.
+
+'''hot add'''
+
+'''hot plug'''
+
+'''hot swap'''
+
+'''hotline'''
+
+'''HTML'''
+
+'''Hyper-Threading'''
+
+'''hypervisor'''
+
+'''Hz'''
+''Also see bandwidth.''
+
+'''I/O'''
+
+'''i.e.''' and '''e.g.'''
+i.e. means “in other words.” e.g. means “for example.” Add commas after each (e.g.,).
+
+'''illegal'''
+Illegal means “prohibited by law,” not “incorrect” or “not permitted.” You may be looking for the word “invalid.”
+
+'''in concert with'''
+Do not use. Instead, simply say “with.”
+
+'''Infrastructure-as-a-Service (IaaS)'''
+
+'''inline'''
+
+'''insecure'''
+Do not use “nonsecure,” “non-secure,” or “unsecured.”
+
+'''installation program'''
+Do not use “installer.”
+
+'''insure'''
+“Insure” relates to monetary insurance. Also see assure and ensure.
+
+'''Intel 64'''
+Do not use “Hammer,” “x86_64,” or “x86-64” as the name of this architecture. The correct term for AMD’s implementation of this architecture is “AMD64.”
+
+'''interesting'''
+Avoid using, as this is a substitute for showing the reader why something is of interest. For example, change “It is interesting to note” to “Note.”
+
+'''Internet'''
+
+'''intranet'''
+
+'''IP (Internet Protocol)'''
+
+'''IPsec (Internet Protocol security)'''
+
+'''is designed to'''
+Avoid this and similar phrases when describing a function.
+
+Incorrect: SSH is designed to work with almost any kind of public key algorithm or encoding format.
+
+Correct: SSH works with almost any kind of public key algorithm or encoding format.
+
+'''just'''
+Use sparingly and avoid when possible. For example, in a phrase like, “Just point your browser to,” omit the word “just.”
+
+'''KB'''
+
+'''kbps'''
+
+'''kernel space''' (n.); '''kernel-space '''(adj.)
+
+'''kilobit, kilobyte'''
+
+'''later/newer'''
+When referring to more recent versions of a product, package, or other software, use “later.” When referring to earlier versions, use “earlier.”
+
+'''left-click'''
+
+'''life cycle'''
+
+'''Linux®'''
+Linux is a registered trademark of Linus Torvalds. It gets a registered trademark symbol on first use.
+
+'''lists'''
+Keep the structure of bulleted lists equivalent and consistent. If one bullet is a verb phrase, they should all be verb phrases. If one is a complete sentence, they should all be complete sentences, etc.
+
+Capitalize the first word of each bullet, unless it is obvious that it is just a list of items, such as a list of items like:
+computer
+monitor
+keyboard
+
+When the bulleted list items complete a sentence or are sentences themselves, use periods on each item. If they do not, or are simply a list of items (like the list above), no periods are necessary.
+
+'''log file'''
+
+'''log in''' (v.); '''log-in''' (adj.); '''login''' (n.)
+
+'''lookup''' (n.); '''look up''' (v.); '''look-up''' (adj.)
+
+'''LVM'''
+
+'''man page'''
+
+'''mashup'''
+
+'''may/can'''
+Use “can” to describe actions or conditions that are possible. Use “may” to describe situations where permission is being given.
+
+'''MB; Mb'''
+MB is short for megabyte (1,000,000 or 1,048,576 bytes, depending on the context). Mb is short for megabit.
+
+'''MBps'''
+
+'''metadata'''
+
+'''Microsoft'''
+Do not use “MS”, “MSFT” or “MicroSoft.”
+
+'''months'''
+Abbreviate months and states according to AP. Months are abbreviated only if they are used in conjunction with a day. Example: “The President visited in January 1999.” or “The President visited Jan. 12.” Abbreviated months: Jan., Feb., March, April, May, June, July, Aug., Sept., Nov., Dec.
+
+'''Mozilla Firefox'''
+Subsequent references can be “Firefox.”
+
+'''Mozilla Thunderbird'''
+Subsequent references can be “Thunderbird.”
+
+'''multi-'''
+Hyphenate words with the prefix “multi” unless the dictionary or this guide says otherwise.
+
+'''multiprocessing'''
+
+'''MySQL'''
+
+'''nameserver'''
+
+'''namespace'''
+
+'''.NET'''
+
+'''newer'''
+
+'''non-'''
+Hyphenate words with the prefix “non” unless the dictionary says otherwise.
+
+'''nonsecure'''
+Use “insecure” instead.
+
+'''NULL''' or '''null'''
+When a command or value is stated, use NULL. When stating that something is null, use “null.”
+
+'''numbers'''
+Write out numbers between one and nine.
+
+Exceptions:
+*Beginning a sentence
+*Preceding another number (four 6-pound bags)
+*Approximations (“thousands of”)
+*Very large values (4 billion)
+*Ranges (4—6 datacenters)
+
+Use numerals for numbers 10 and greater, negative numbers, fractions, percentages, decimals, measurements, references to book sections (Chapter 3, Table 5, Page 11), and numbers less than 10 if they appear with numbers of 10 or greater (“You answered 8 out of 14 questions correctly”). Also use numerals when referring to code (such as x = 6) and release versions (Fedora 18).
+
+'''numbered lists'''
+Lists should always consist of more than two items. Use bullets for a list in which the order of items is unimportant. Use a numbered list only when the order is important, as in a series of steps.
+
+'''Objective C'''
+
+'''object-oriented'''
+
+'''OEM (original equipment manufacturer)'''
+
+'''offline'''
+
+'''online'''
+
+'''on-site'''
+Hyphenated when used as an adjective, as in “on-site labs.”
+
+'''on demand''' (adv.); '''on-demand''' (adj.)
+
+'''opcodes'''
+
+'''open source'''
+
+'''operating system'''
+
+'''orientate'''
+>Do not use. A user becomes “oriented” to an environment.
+
+'''over'''
+When referring to something quantifiable, use “more than” instead.
+
+'''override'''
+
+'''packet-switching'''
+
+'''pc''' or '''PC'''
+When referring to program counter, use pc. The first instance must have the acronym defined, such as “program counter (pc).” When referring to a general computer, use “PC.”
+
+'''percent (%)'''
+Use the percent sign (%) whenever referring to numerical percentages.
+Example: In a survey, 60% of users said they were satisfied with their technology solution.
+Exception: Press releases and press blogs follow strict AP style, which spells out 'percent' in all uses.
+
+'''peer-to-peer architecture'''
+
+'''Perl'''
+
+'''plain text'''
+
+'''Platform-as-a-Service (PaaS)'''
+
+'''please'''
+Do not use. Instead of “Please refer to the Getting Started Guide,” write, “Refer to the Getting Started Guide.”
+
+'''plug-in''' (n); '''plug in''' (v)
+As a noun, “plug-in” is a hardware or software module that adds a specific feature or service to a larger system.
+
+'''p.m.'''
+''See a.m.''
+
+'''pop-up'''
+
+'''PostScript'''
+
+'''PowerPC'''
+Do not use “PPC” or variants.
+
+'''PPP'''
+
+'''proximity'''
+Don’t use “close proximity.” It’s redundant.
+
+'''pseudo-ops'''
+
+'''pulldown'''
+
+'''quotations'''
+“Place the punctuation inside the quotes,” said the editor. Except in rare instances, use only “said” or “says” for quotes. Other words liked “noted” or “quipped” get in the way of the quote itself and tend to editorialize.
+
+Place “said” first, followed by the name: “Friends, freedom, features, first,” said Beefy Miracle.
+
+'''regardless'''
+“Irregardless” is not a word.
+
+'''read-only'''
+
+'''read/write'''
+
+'''real-time''' (adj.); '''real time''' (n)
+
+'''reboot'''
+
+'''recursive'''
+
+'''Red Hat'''
+Write “Red Hat.” Not “Red Hat, Inc.” (The only exceptions to this rule are when the company itself is writing legal or financial statements.) “Red” and “Hat” should be on the same line together. Don’t let them be separated by a line break.
+
+Pronoun and verb agreement: A company is singular in the US. In other words, Red Hat is an “it,” not a “they.”
+
+'''right-click'''
+
+'''roadmap'''
+
+'''RPM'''
+
+'''runlevel'''
+
+'''runtime'''
+
+'''screenshot'''
+
+'''scrollbar'''
+
+'''SELinux'''
+
+'''server side''' (n.); '''server-side''' (adj.)
+
+'''set up''' (v.); '''setup''' (n.); '''set-up''' (adj.)
+
+'''sign up''' (verb), '''sign-up''' (noun, adjective)
+
+'''shut down''' (v.)
+
+'''simply'''
+Do not use. See basically.
+
+'''since'''
+'See because.''
+
+'''smart card'''
+
+'''soft copy'''
+Do not use.
+
+'''Software-as-a-Service (SaaS)'''
+
+'''sound card'''
+
+'''space'''
+Use when referring to white space, such as “Ensure there is a space between each command.” Use “spacebar” when referring to the keyboard key.
+
+'''spaces''' (using)
+Use only one space between sentences. Use no spaces around an em-dash.
+
+'''spec file'''
+
+'''standalone'''
+
+'''startup'''
+
+'''states'''
+Use the two-letter postal abbreviations. See stateabbreviations.us for a list.
+
+'''stovepipe'''
+
+'''subdirectory'''
+
+'''submenu'''
+
+'''superuser'''
+
+'''swap space'''
+
+'''SysV'''
+
+'''taskbar'''
+
+'''Telnet'''
+
+'''that/which'''
+“That” introduces a restrictive clause — a clause that must be there for the sentence to make sense. A restrictive clause often defines the noun or phrase preceding it.
+
+“Which” introduces a non-restrictive, parenthetical clause — a clause that could be omitted without affecting the meaning of the sentence. Use”who” or “whom,” rather than “that” or “which,” when referring to a person.
+
+For example: The car was travelling at a speed that would endanger lives. The car, which was travelling at a speed that would endanger lives, swerved onto the sidewalk.
+
+'''that vs. who'''
+Use "that" when referring to places and things, including groups (e.g., customers), teams, and companies. Use "who" when referring to individual persons.
+
+'''then/than'''
+“Then” refers to a time in the past or the next step in a sequence.
+“Than” is used for comparisons.
+
+'''third-party'''
+
+'''this'''
+The word “this” can be used as an adjective or a pronoun. If you use it as a pronoun, be clear what the antecedent is. If it is unclear, use the adjective form by following “this” with a noun.
+
+'''throughput'''
+
+'''time zone'''
+
+'''timeout'''
+
+'''token-ring'''
+
+'''toolbar'''
+
+'''troubleshoot'''
+
+'''under'''
+When referring to something quantifiable, use “fewer than.”
+
+'''UNIX'''
+UNIX is a registered trademark of The Open Group. Do not use “UNIX-like.” Use an expression like “Linux, UNIX, and similar operating systems” instead.
+
+'''upgrade'''
+
+'''URLs'''
+For URLs that begin with http://www., you may omit that portion and give the main URL, such as fedoraproject.org. If it begins with ftp or https, you should include the full URL.
+
+'''US''' (adjective), '''United States''' (noun)
+
+'''usable'''
+
+'''userid'''
+
+'''user interface'''
+
+'''username'''
+
+'''user space'''
+
+'''utilize'''
+Avoid this term. Write “use” instead.
+
+'''vi, Vim'''
+
+'''virtualization'''
+
+'''Web 2.0'''
+Avoid using this term.
+
+'''web, web browser, webmaster, web server, website'''
+
+'''white space'''
+
+'''whitepaper'''
+
+'''workflow'''
+
+'''worldwide'''
+
+'''writable'''
+
+'''x86'''
+
+'''Xen'''
+
+'''X Window System'''
+
+'''ZIP code'''
+-->
+ </section>
+ <section id="sect-documentation_guide-style-quick_reference">
+ <title>Quick Reference</title>
+ <para/>
+ <section id="sect-documentation_guide-style-quick_reference-numbers">
+ <title>Numbers</title>
+ <para/>
+ <section id="sect-documentation_guide-style-quick_reference-numbers-when">
+ <title>When to Spell Out a Number</title>
+ <para>Rules for using Arabic numerals or spelling out numbers are as follows and are listed from highest priority to lowest.
+ <simplelist>
+ <member>If the number is part of a casual expression, spell it out.</member>
+ <member>If the number is a calendar year, do not spell it out.</member>
+ <member>If the number is an age or percentage, do not spell it out.</member>
+ <member>If the number begins a sentence, spell it out. Awkward sentences should be reformed.</member>
+ <member>If the number is greater than 10, do not spell it out.</member>
+ <member>If the number is one through nine, spell it out.</member>
+ </simplelist>
+ </para>
+ </section>
+ <section id="sect-documentation_guide-style-quick_reference-numbers-roman_numerals">
+ <title>When to use Roman numerals</title>
+ <para>Use Roman numerals for wars and honorific suffixes.
+ <simplelist>
+ <member>World War II</member>
+ <member>John Doe III</member>
+ </simplelist>
+ </para>
+ </section>
+ <section id="sect-documentation_guide-style-quick_reference-numbers-cardinal_numbers_and_ordinals_numbers">
+ <title>Cardinal Numbers and Ordinal Numbers</title>
+ <para>Cardinal numbers include figures 1, 2, 10, 101, and so on, and the corresponding words.</para>
+ <para>Ordinal numbers include the terms 1st, 2nd, 10th, 101st, and so on, and the corresponding words.</para>
+ </section>
+ <section id="sect-documentation_guide-style-quick_reference-numbers-large_numbers">
+ <title>Large Numbers</title>
+ <para>When spelling out large numbers, connect words ending in 'y' to subsequent words within the same number with a hyphen. Avoid commas between words that are part of one number.
+ <simplelist>
+ <member>twenty-one</member>
+ <member>one hundred thirty-one</member>
+ <member>twenty-five thousand one hundred thirty-one</member>
+ <member>ninety bottles</member>
+ </simplelist>
+ </section>
+
+<!--
+==== Proper Names ====
+
+* Write proper names according to the owner's practice.
+
+=== Abbreviations ===
+
+==== The United States ====
+
+* As a noun appearing alone, use "United States."
+
+<pre>
+...the government of the United States...
+</pre>
+
+* As a noun appearing as part of a locality, use "US" with no periods and no spaces.
+
+<pre>
+Raleigh, NC, US
+US, Earth
+</pre>
+
+* As an adjective, use "U.S." with no spaces.
+
+<pre>
+...the U.S. government...
+</pre>
+
+===== States =====
+
+* Spell out state names when they appear alone.
+
+<pre>
+...the government of North Carolina...
+</pre>
+
+* When abbreviating state names, use their two-letter ZIP standard abbreviations.
+* Abbreviate state names when they appear as part of a locality.
+
+<pre>
+Raleigh, NC
+</pre>
+
+* Place one comma between the city and state name and another after the state name, unless it ends the sentence or is part of a dateline.
+
+<pre>
+...founded in Raleigh, NC, by Red Hat...
+...managed from Raleigh, NC.
+</pre>
+
+==== Academic Degrees ====
+
+* Avoid abbreviating degrees.
+* Use an apostrophe in bachelor's degree, master's, etc.
+* Do not use an apostrophe in Bachelor of Arts, Master of Science, etc.
+* Use abbreviations only when the preferred method would be cumbersome.
+* Use abbreviations only after a full name.
+* Set abbreviations apart with commas.
+
+==== Dates ====
+
+* Spell out days of the week and separate them from dates using a comma.
+* When listing a day, month and year, use ISO 8601 dates (YYYY-MM-DD). Read more about dates and times on the [http://fedoraproject.org/wiki/DocsProject/StyleGuide/DatesAndTimes DatesAndTimes] page.
+* When listing a day and month:
+* List the day first.
+* Spell out the day.
+* Set the day and month apart with "of."
+* Spell out the month.
+* When listing a month and year:
+* List the month first.
+* Spell out the month.
+* Set the month and year apart with "of."
+* Use Arabic numerals for the year.
+
+<pre>
+Sunday, 2000-01-01
+2000-01-01
+The first of January
+January of 2000
+</pre>
+
+==== Times ====
+
+* Use 24-hour time formats.
+* Always use figures.
+* Follow absolute times with a timezone specification.
+* Separate days, hours, minutes and seconds with a colon and no spaces.
+* Separate seconds and fractions thereof with periods.
+* If the scope of a specification is unclear, increase the precision or specify the scope of the lowest precision.
+* Use Coordinated Universal Time (UTC) for all worldwide events. Refer to the [http://fedoraproject.org/wiki/DocsProject/StyleGuide/DatesAndTimes DatesAndTimes] page for more information about UTC.
+* Localized events may be specified using UTC or the local time, but always specify a timezone or offset.
+
+<pre>
+15:00 UTC
+1:15:00:00.50 (1 day, 15 hours, 0 minutes, 0 seconds and 50/100 of one second)
+15:00 minutes (15 minutes)
+15:30 hours (15 hours and 30 minutes)
+The global conference will take place at 15:00 UTC.
+The event will be in Raleigh, NC, and will take place at 11:00 UTC-4.
+</pre>
+
+=== Punctuation ===
+
+==== Periods ====
+
+==== Commas ====
+
+For consistency and to avoid ambiguity, use a serial comma after every item in a list save the last. This usage is sometimes called the "Harvard comma" or the "Oxford comma."
+
+<pre>spam, spam, spam, and eggs
+</pre>
+
+Do not use a serial comma in the name of companies such as law firms.
+
+<pre>Dewey, Cheatam & Howe
+</pre>
+
+==== Colons ====
+
+==== Other Punctuation ====
+
+{{Anchor|Lists}}
+=== Lists ===
+
+* Capitalize and use periods when the list items are complete sentences.
+* Make them agree so that there aren't a mixture of sentences and fragments.
+
+You could also have a list with a colon:
+* that was lowercase and not punctuated
+* that again doesn't mix forms
+* that is likely very short
+
+=== Titles ===
+
+* Avoid punctuation in titles, with the exception of hyphens.
+* Avoid abbreviations in titles. Spell words out and introduce abbreviations in the body text.
+
+=== Units of Measure ===
+
+* Metric units are preferred.
+* Use the prefixes published by the International Electrotechnical Commission (IEC) as part of IEC 60027-2 A.2 to express quantities of binary data.
+
+=== Markup ===
+
+=== Common Technology Terms ===
+
+* cyberspace
+* database
+* dot-com
+* DSL
+* email
+* FLOSS (free/libre open source software)
+* home page
+* hyperlink
+* hypertext
+* Internet
+* intranet
+* log in (intransitive verb)
+* log into
+* login (noun)
+* online
+* shareware
+* Web (proper noun)
+* webcast
+* webmaster
+* website
+* World Wide Web
+
+=== Denoting trademarks ===
+
+Never use the trademark symbol (™) or the registration mark (®). If for any reason the Fedora Project is obliged by contract to mention other trademarks in a legend, add the legend as required by the contract.
+
+In addition, all documentation should contain the disclaimer: "All other trademarks are the property of their respective owners." This marking is standard in all Fedora Documentation toolchains at the time of this writing.
+
+-->
+ </section>
+ </section>
</chapter>
More information about the docs-commits
mailing list