From fedora-docs-commits at redhat.com Wed Jun 10 15:33:03 2015 Content-Type: multipart/mixed; boundary="===============3751451739094221629==" MIME-Version: 1.0 From: fedora-docs-commits at redhat.com To: docs-commits at lists.fedoraproject.org Subject: documentation-guide/en_US emacs-nxml.xml, NONE, 1.1 emacs.xml, NONE, 1.1 fdp-info.xml, NONE, 1.1 getting-files.xml, NONE, 1.1 intro.xml, NONE, 1.1 module-struct.xml, NONE, 1.1 style.xml, NONE, 1.1 tutorial.xml, NONE, 1.1 vim.xml, NONE, 1.1 writing-guidelines.xml, NONE, 1.1 xml-tags.xml, NONE, 1.1 documentation-guide.xml, 1.4, 1.5 docs-emacs-nxml.xml, 1.1, NONE docs-emacs.xml, 1.2, NONE docs-getting-files.xml, 1.2, NONE docs-intro.xml, 1.2, NONE docs-module-struct.xml, 1.2, NONE docs-rh-guidelines.xml, 1.3, Date: Sat, 03 Feb 2007 17:22:00 -0500 Message-ID: <200702032222.l13MM0Oq032113@cvs-int.fedora.redhat.com> --===============3751451739094221629== Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: quoted-printable Author: kwade Update of /cvs/docs/documentation-guide/en_US In directory cvs-int.fedora.redhat.com:/tmp/cvs-serv32086 Modified Files: documentation-guide.xml = Added Files: emacs-nxml.xml emacs.xml fdp-info.xml getting-files.xml = intro.xml module-struct.xml style.xml tutorial.xml vim.xml = writing-guidelines.xml xml-tags.xml = Removed Files: docs-emacs-nxml.xml docs-emacs.xml docs-getting-files.xml = docs-intro.xml docs-module-struct.xml docs-rh-guidelines.xml = docs-style.xml docs-tutorial.xml docs-vim.xml = docs-xml-tags.xml = Log Message: renaming rh-guidelines to writing-guidelines --- NEW FILE emacs-nxml.xml --- %FEDORA-ENTITIES-EN; ]> Emacs and nXML Mode = nXML = Emacs Emacs nXML mode You can also use the nXML mode available for Emacs to make it even easier to write in Doc= Book XML format. nXML mode provides context-sensitive editing using completi= on, real time validity error checking, syntax highlighting and indentation.= All you need to do is install an RPM!! Early stages Please be aware the nxml-mode for Emacs is quite new, so there are a few things that the advanced user might not= ice when using it with other documents types. If you keep an eye on the mailing-list, you can keep up to date with these, as well as ask questions. For more details, check out . = Getting the nXML RPM nXML RPM = nXML RPM = To use nXML mode with emacs, you will need to install the nXML RPM available from Tim Waugh's website or the source from http://www.thaiopensource.= com/download/. = The source requires a lot more work to setup, therefore we will only = be concentrating on the RPM version. Information on where to get the source is available in . = Examples = Compared to PSGML mode there are only couple of commands that you nee= d. This speeds up writing with Emacs consider= ably, which means you can concentrate more on the content of your article. Commands = To create a tag, type < and then type the keyword. To complete the keyword, press Ctrl-Ret, then add the last >. To close a tag, type </. Important When you open a document that doesn't have a DOCTYPE declaration at the top of the file, you will get this message and tag completion won't work because nXML will not know what format you are writing. To load the schema, type Ctrl-c, then Ctrl-s and navigate to /usr/share/emacs/site-lisp/nxml-mode/schema/ and load docbook.rnc. Emacs will then prompt you to save it in the current working directory. = Tip The commands already discussed are the only differences between using Emacs with PSGML mode and Emacs with nXML mode. You will still need to use all the same commands as discussed in . Additional Resources Additional Emacs and nXML references are available at the follow= ing locations: http://www.thaiopensou= rce.com/download/ = — Author's download area http:= //wks.uts.ohio-state.edu/unix_course/intro-135.html = — Emacs Quick Reference Guide = Emacs reference card that comes with the emacs package. You can print it out as a reference. — /usr/share/emacs/<version>/et= c/refcard.ps nXML README File Note This file can be found in the directory you extracted the source into, or in /usr/share/doc/nxml-mode-<version>/ = if you installed the RPM. README file: This is a new major mode for GNU Emacs for editing XML documents. It supports editing well-formed XML documents and also provides schema-sensitive editing of XML documents using RELAX NG Compact Synt= ax. = To use this, you need GNU Emacs version 21.x, preferably 21.3. GNU Em= acs version 20 will not work properly, nor will XEmacs. To get started, d= o the following: M-x load-file RET rng-auto.el RET = This defines the necessary autoloads. Now, visit a file containing a= n XML document, and do the following: M-x nxml-mode Now do = = C-h m For information on how to use nxml-mode. The beginnings of a manual = are in nxml-mode.info. You can read this using: C-u M-x info RET nxml-mode.info RET It's also installed as an entry at the end of the top-level info directory. So you can read it with C-h i as usual. You can use test.valid.xml and test.invalid.xml as examples of valid and invali= d XML documents. To get things automatically loaded each time you start Emacs, add: (load "~/nxml-mode-200YMMDD/rng-auto.el") to your .emacs, where ~/nxml-mode-200YMMDD is the directory containing the .elc files. Note that rng-auto.el does not load all of the nxml-mode c= ode; it merely sets things up so that all the features of nxml-mode will be autoloaded properly. You should not try to autoload rng-auto.el itself. To use nxml-mode automatically for files with an extension of xml, xsl, rng or xhtml, add the follo= wing to your .emacs file: (setq auto-mode-alist (cons '("\\.\\(xml\\|xsl\\|rng\\|xhtml\\)\\'" . nxml-mode) auto-mode-alist)) If you edit XML using iso-8859-N encodings other than iso-8859-1 and = you are running Emacs 21.3 or later, then I recommend enabling unify-8859-on-decoding-mode, by adding the following to your .emacs file: (unify-8859-on-decoding-mode) To get validation and schema-sensitive editing, you need a RELAX NG Compact Syntax (RNC) schema for you document. The schema directory includes some schemas for popular document types. For more on RELAX NG, refer to http://relaxng.org/. For a tutorial on RELAX NG Compact Syntax, refer to http://relaxng.org/compac= t-tutorial.html For automatically creating RNC schemas, I recommend my Trang program: http://eee.thaiop= ensource.com/relaxng/trang.html" You can use this to = Infer an RNC schema from an instance document Convert a DTD to an RNC schema Convert a RELAX NG XML syntax schema to an RNC schema To convert a RELAX NG XML syntax (.rng) schema to a RNC schema, you c= an also use the XSLT stylesheet from http://www.pantor.com/download= .html". To convert a W3C XML Schema to an RNC schema, you need first to conve= rt it to RELAX NG XML syntax using Sun's RELAX NG converter tool rngconv (b= uilt on top of MSV). Refer to https://www.dev.java.net/. The file NEWS describes recent changes. Please use the list http://groups.yahoo= .com/group/emacs-nxml-mode = for bug reports, discussion. I will announce all new versions there. James Clark jjc(a)thaiopensource.com ***** Error reading new file: [Errno 2] No such file or directory: 'emacs.x= ml' --- NEW FILE fdp-info.xml --- Fedora Documentation Guide 2003 2004 2005 2006 Red Hat, Inc. Tammy Fox Johnray Fuller Sandra Moore Paul W. Frields Fox Tammy Fuller Johnray Moore Sandra Frields Paul 0.2.6.3 2005-09-18 Update to new build requirements --- NEW FILE getting-files.xml --- %FEDORA-ENTITIES-EN; ]> Prerequisites To work on official &FED; documentation you need to install the required tools. Follow the directions below to configure your system.
System Packages Install the "Authoring and Publishing" package group, which contains required DocBook XML files, stylesheets and scripts: su -c 'yum groupinstall "Authoring and Publishing"' Next, install the cvs package, which is used to handle revision control on files in the official repository: su -c 'yum install cvs'
Fedora Documentation Tools The &FDP;'s custom scripts and stylesheets are stored in CVS on the cvs.fedoraproject.org= CVS server. Check them out along with the DocBook XML files for the exis= ting docs. mkdir my-fedora-docs-sandbox cd my-fedora-docs-sandbox export CVSROOT=3D:ext:username@cvs.fedora.redhat= .com:/cvs/docs cvs login cvs co docs-common At the password prompt, press the Enter key. Common Files You need to perform this "checkout" step only once, although you may need to update the files later. These files are common to all the official documentation. To work on existing documents in CVS, refer to .
Filename Conventions &FDP; provides the tools, scripts, and stylesheets to transform your XML documents into other output formats such as HTML. In addition, these tools can build your docum= ent into a RPM package. To take advantage of these services, you must follow conventions for naming your files.
Document Filenames Each document lives in a peer directory to the docs-common directory you extracted from the &= FED; archive earlier. On the CVS server, these directories are called modules. Choose a module name that accurate= ly reflects your document's subject, but avoid any name already taken.= Use the cvs co -c command to view existing module na= mes. Avoid Redundancy Do not use the word &FED; in your module name. Since all documents in the repository are &FED; documentation, using this term creates unnecessary confusion.
***** Error reading new file: [Errno 2] No such file or directory: 'intro.x= ml' --- NEW FILE module-struct.xml --- %FEDORA-ENTITIES-EN; ]> How Modules Work Documentation modules have a specific structure that enables the preconfigured tools to work correctly. Follow this structure exactly o= r you may have problems building your module. The &FDP; build tools locate resources in the module and use them to build new output such as HTML o= r RPM packages.
Structure of a Module shows a directory tree of an example module, excluding any CVS folders: Example Module Structure Primary language directory (required) This is the only directory absolutely required. It is named for= the original language of the document, such as en_US (US English). The primary language does not have to be US English; all languages are supported. This directory contains all the XML source for the actual document, as well as XML source for document-specific entities Think of an XML entity as a predefined snippet of information. It can represent a chunk of XML source, or simply a word or character. If the information changes, it need be replaced only once, in the definition, to fix all usage. . Graphics directory (optional) The figs/ directory is= an optional directory where graphics for the document should be stored. If graphics are screenshots that are particular to a language, the figs/ directory can and should be stored in a language directory. Translation (PO) directory (optional) = The po/ directory cont= ains specially formatted files created and used by translators. The &FDP; build tools use these files to create translated versions of documents. The translated documents are not stored in CVS; they are created as needed from these PO files. Makefile (required) The Makefile controls the build process. I= ts content is discussed in . <filename>rpm-info.xml</filename> (required) The rpm-info.xml file contains document specific metadata
The Document Build System The build system can render the document into another format such as HTML or PDF, using make(1) and shell scripts. Authors need no prior experience with either shell scripts or a make(1).
The Document <filename>Makefile</filename> Each individual document has its own Makefile, which only needs to be a few lines long. The document Makefile content is designed for cut and paste operations. below shows the whole Makefile for a simple document with two files and two translations. Sample Document Makefile Do not be concerned with some of the more complicated syntax such as the XMLFILES_template stanza. An explanation for this template appears a few paragraphs below. <systemitem class=3D"macro">DOCBASE</systemitem> This variable contains the name for the main (parent) XML document. Follow convention by naming your document after the module name. <systemitem class=3D"macro">PRI_LANG</systemitem> This variable contains the ISO code for the original version of the document, such as en_US. <systemitem class=3D"macro">OTHERS</systemitem> This variable contains a listing of ISO codes for any other versions into which the document has been translated. The module must contain a po/ directory and a PO file for any indicated additional languages. <systemitem class=3D"macro">DOC_ENTITIES</systemitem> This variable contains a listing of any files containing entity definitions. The &FDP; uses a special XML format to record document-specific entities, so they can be translated and built on the fly like any other XML document. An example is shown later in this guide. <systemitem class=3D"macro">XMLFILES_template</systemitem> This template allows the build tools to work with the document in multiple languages once it is translated. The ${1} marking is a variable used to substitute the appropriate language. This template is not terribly complicated. For a new module, duplicate this section exactly except for the actual filenames. Prepend the text ${1}/, in place of the language code directory name, to each filename in your document. Files Exempt From Listing Do not include the document-specific entities XML file or the rpm-info.xml file, which will be discussed later in this guide. The final line, beginning with include, references the main Makefile for the build system. This Makefile.common file contains all the make(1) targets and rules to actually build the document and the various archives.
The Document <filename>rpm-info.xml</filename> Each document module's primary language directory contains a file called rpm-info.xml. This file contains document-specific metadata used to generate revision history, copyright, and contributor information. It follows a DTD specification included with the rest of the build system tools. illustrates the content of this file: Example <filename>rpm-info.xml</filename> File OPL 1.0 2006 John Q. Smith My Tutorial A tutorial about something important
First draft
]]>
If you are not familiar with XML editing, copy and paste this file from an existing module and then edit the values for the various elements as appropriate. Consult &FDP; members and help channels for more assistance if needed.
Build System Actions To render the XML document into another format, use one of the following make targets: <systemitem class=3D"macro">html</systemitem> This target builds the "chunked" HTML document for each defined translation. Output is placed in a separate directory named ${DOCBASE}-${LANG}/. Each document section is a separate file within that directory. <systemitem class=3D"macro">html-nochunks</systemitem> This target builds the "non-chunked" HTML document for each defined translation. Output is placed in a single file: ${DOCBASE}-${LANG}.html; no other files are created. <systemitem class=3D"macro">pdf</systemitem> This target builds only the PDF document for all document languages. PDF production is currently erratic and may not work for your document. <systemitem class=3D"macro">tarball</systemitem> This target builds only the tar(1) archive for all document languages. <systemitem class=3D"macro">all</systemitem> This target builds all targets listed above. <systemitem class=3D"macro">clean</systemitem> This target deletes any temporary, or generated files, but does not erase any HTML, PDF, or archive files. <systemitem class=3D"macro">distclean</systemitem> This target erases all HTML, PDF, and archive files. This target automatically invokes the clean target as well.
Adding or Changing Targets To add a new target and rules, place them at the bottom of the document Makefile, below the include line. Follow your target definitions with a double colon, not a single colon. The double colon allows you to specify additional rules for existing targets, or to write rules for a new target. For more information on using make(1), consult the online documentation with the command info make in a terminal.
Using Document Image Files Tutorial documents often make use of images such as .PNG files. Store image files in a figs/ folder in the main module directory, as shown in . Depending on the output media, sometimes images may be scaled, streteched, or squashed. To minimize any distortions, we recommend that you use only .PNG images. Avoid .JPG files. The convert(1) program, from the ImageMagick RPM package, provides a convenient way to reformat .JPG images into .PNG format. For more information on formatting images such as screenshots, refer to . Image files may be organized into subdirectories under figs/ if necessary. The document building system recreates the image subdirectory structure in the output documents. Images often contain labels or other text which may need to be localized. A screenshot of a program, for example, may require a version for each translated language. Name language-dependent image files such as program screenshots by adding the language code to the filename, such as menu-en_US.png. Language-independent images, such as icon.png, do not need language codes. Sometimes, a document may require images that do not follow the naming convention. To use these images with the document building system, create an ordinary text file containing the image filenames. This file must be named figs/Manifest-${LANG} so the build system finds it when searching for image filenames. demonstrates one way to create this Manifest file. Building A Manifest /tmp/manifest mv /tmp/manifest figs/Manifest-en]]>
Adding a New DocBook XML File To add a new DocBook XML file to an existing document, follow these steps: Place the new DocBook XML file in the primary language directory. Edit the Makefile and add the filename to the XMLFILES-${1} listing. Append a \ to the last existing line, and on the next line add an entry for the new file. Remember to add the ${1}/ prefix as a substitute for the language directory name.
Adding a Translation Translations are stored as PO (portable object) files, which the toolchain transforms into translated documents. Each PO file is based on the POT (PO template) for the document and translated by the &FED; Translation Project. To add a translation, follow these steps: If the po/ directory does not exist, create it and add it to CVS: If it does not exist, create the POT file: Add the new translation language to the OTHERS listing in the Makefile. Although translators often copy the POT manually to create the new PO file, the following command also works: make po/lang.po
--- NEW FILE style.xml --- %FEDORA-ENTITIES-EN; ]> = Style Writing good technical documentation is not simply reproducing command lines and instruction sets. Good documentation is easy to read, understand, and translate, and presents a concise logical progression of concepts. Good documentation can also be defined by what it does not contain. Your tutorial should avoid: Excessive wordiness Unnecessary or undefined jargon Grammatical or spelling errors References to yourself or your experiences Remarks which might offend or confuse any reader This chapter contains style rules and guidelines for writing &FED; documentation. Guidelines are not the same as rules. It is acceptable to violate a guideline when it makes your material easier to understand. Follow guidelines whenever possible, but follow rules at all times. Assume any advice is a guideline unless identified otherwise.
= Why Style Is Important = Writing well comes naturally to almost no one. It is a skill that professional writers, even famous ones, must practice constantly. Style style is the quality that separates elegant writing from the merely functional. Elegance comes in many forms. In prose and poetry, elegant writing may not follow some (or any) common rules of grammar, syntax, or spelling. A good example is Episode 18, "Penelope," in James Joyce's novel Ulysses For example, refer to. http:= //www.online-literature.com/james_joyce/ulysses/18/. = Please note that this example contains some mature themes and language, and is not suitable for all readers. . There, Joyce uses long streams of words without punctuation to simulate a character's internal consciousness. By violating basic rules of grammar and syntax, Joyce simulates the disorganized but loosely connected thought patterns of the narrator. Technical documentation, however, should always respect these rules. The more a document departs from standard language usage, the more difficult the material becomes for the reader. For example, readers may not be native speakers of the language used, or they might be reading a translation. If the writer uses slang, idioms, or jargon, a reader or translator may easily become confused. The following example compares two different written executions of the same idea: Incorrect style So you made the changes I showed you in the last section. What's the next thing you should do? Just pop your thumb drive onto your system and read the messages log. When you see "USB device found," then Bob's your uncle. Correct style = = After you complete the configuration changes above, attach the USB removable media to your system. Use the dmesg command to examine the kernel message log. The message USB device found indicates that your device was installed successfully. The first example is more conversational English, which is not appropriate for official written documentation. The second example is more formal, but as a result it is easier to comprehend, both for native readers and translators. Following style rules and guidelines also makes readers more comfortable with a set of documents. Consistent style enhances the professional appearance of documentation, and its perceived value. On the other hand, lapses in punctuation or poor grammar negatively affect a reader's reaction to written material. A reader can feel that an otherwise correct technical document is lacking in authority, simply because it is poorly written. Readers feel at ease when they do not have to struggle to understand an author's use of language. This chapter cannot possibly cover enough material to make every reader a good writer. Some manuals devoted entirely to writing style are themselves hundreds of pages long. This chapter provides enough guidelines for intermediate writers to understand style usage in technical documentation. If you are not a practiced writer, whether of technical documentation or otherwise, you may benefit from other style resources. The following list is far from comprehensive, but provides a starting point: The Elements of Style, by William Strunk. Basic rules and links to online versions can be found at: http://en.w= ikipedia.org/wiki/The_Elements_of_Style = The Chicago Manual of Style, by the University of Chicago Press. Online version: http://www.chicagomanualo= fstyle.org/ Paradigm Online Writing Assistant, maintained by Chuck Guilford, Ph.D. Online only: http://www.powa.org/ There are many free software documentation projects which have developed their own style guidelines. This chapter, in fact, draws heavily on the GNOME Documentation Style Guidelines (GDSG). You may read the original GDSG at http://developer= .gnome.org/documents/style-guide/. =
=
= Fundamental Concepts of Technical Documentation = Bibliographic Information This section is drawn primarily from the GDSG. = This chapter provides a brief introduction to writing technical documentation.
General Style Requirements Technical writing for the &FP; imposes special constraints beyond the basic requirements of good prose. Good &FED; technical documentation has the following characteristics: Comprehensive Describe all of the functionality of a product. Do not omit functionality that you regard as irrelevant for the user. Conforming Describe what you see. Do not describe what you want to see. Present your information in the order that users experience the subject matter. = Clear Read The Elements of Style (http://en.wiki= pedia.org/wiki/The_Elements_of_Style) = to help make your writing clear. Consistent Use agreed vocabulary throughout your documentation. Use the same vocabulary as other writers who are working on related documentation. Concise Review your work frequently as you write your document. Ask yourself which words you can take out. Refer to for specific guidelines.
Golden Rules This section contains some basic style guidelines. Subsequent sections in this chapter expand on these guidelines to give more detailed guidance. Golden Rule 1: Be brief Limit each sentence to fewer than 25 words. Limit each procedure step to 23 words. Incorrect: Too long Under normal operating conditions, the kernel does not always immediately write file data to the disks, storing it in a memory buffer and then periodically writing to the disks to speed up operations. Correct: Less wordy Normally, the kernel stores the data in memory prior to periodically writing the data to the disk. Golden Rule 2: Be organized Limit each paragraph to one topic. Limit each sentence to one idea. Limit each procedure step to one action. Incorrect: Disorganized topics The Workspace Switcher applet helps you navigate all of the virtual desktops available on your system. The X Window system, working in hand with a piece of software called a window manager, allows you to create more than one virtual desktop, known as workspaces, to organize your work, with different applications running in each workspace. The Workspace Switcher applet is a navigational tool to get around the various workspaces, providing a miniature road map in the GNOME panel showing all your workspaces and allowing you to switch easily between them. Correct: Organized topics Use the Workspace Switcher to add new workspaces to the GNOME Desktop. You can run different applications in each workspace. The Workspace Switcher applet provides a miniature map that shows all of your workspaces. You can use the Workspace Switcher applet to switch between workspaces. Plan the order of paragraphs before you start writing. Decide which topic you want to cover in each paragraph. Golden Rule 3: Be demonstrative Use explicit examples to demonstrate how an application works. Provide instructions rather than descriptions. Incorrect: Describes but does not demonstrate There is a text box that you can use to find out the definition of a word. Correct: Demonstrates usage To request a definition of a word, type the word in the text box, then select Lookup. Do not apply this guideline too rigidly. Sometimes you must explain how software works to support your how-to examples. Golden Rule 4: Be objective Write in a neutral tone. Incorrect: Sentence takes sides The applet is a handy little screen grabber. Correct: Sentence is objective Use the applet to take screenshots.
Tone Inappropriate tone hinders reader access to information. A neutral tone free of opinion or personal flavor improves the reader's comprehension. Neutral tone helps writers to work in parallel on a large technical documentation project. Furthermore, additional writers may join the project at any time. Use of a neutral tone helps to achieve consistency across a documentation set, and thereby facilitates user access to information. The best way to achieve a common, neutral tone is to apply the following principles: Avoid humor Humor distracts from the information you are trying to provide. Humor also makes documentation difficult to translate. Stay factual. Avoid personal opinions Whether you think a function is useful or woeful is irrelevant. Report the function to the user, with instructions about how to use the function. Stay accurate. Avoid colloquial language Colloquial language is difficult to translate and usually culture-specific. Stay neutral. Avoid topical expressions An expression that is in common use today might convey something completely different tomorrow. Stay technical. Avoid aspirational statements Statements about the future developments of a product do not belong in technical documentation. Write about what you see right now. Stay real.
Reaching the Right Audience All of the decisions that you make about the structure and content of a manual follow from an understanding of the audience. Consider how the audience accesses the documentation, what sort of information the audience needs, and the experience level of the audience. Usually, you need to create documentation that is suitable for different audiences. The following sections introduce some of the audience-related topics you need to consider.
User Motivation Do not waste the time of the user who looks for information in your documentation. Users do not read technical documentation for entertainment. Users usually have specific questions. You need to give clear answers to those questions.
New Users New users to &FC; are likely to consult online tutorials for guidance about unfamiliar applications or functionality. Each tutorial should contain enough introductory information to tell new users how to start using the relevant functions. Each tutorial should also contain enough usage instructions to tell users the different actions that they can perform with the command or function. Keep these instructions task-oriented. Do not describe GUI screens, dialogs, and dialog elements in a tutorial, unless there is an unusual feature that affects your instructions.
Experienced Users Experienced users are more likely to use documentation as a reference. The documentation therefore needs to be complete, well-organized, and in the case of printed manuals, well-indexed.
Do Not Offend Your Audience To avoid offending your readers, apply the following guidelines to your documentation: Avoid insider language Insider language includes both undefined jargon and the tendency of the computer community to shorten words. For example, use the term documentation instead of the term docs. A term may be jargon if it fails all the following conditions: The term does not appear in the &FED; Jargon Buster (http://fedora.re= dhat.com/docs/jargon-buster/). The term does not appear in the American Heritage Dictionary (http://www.bartleby.com/61/ = ). The term does not appear in the glossary of the manual that you are writing. The term is not defined in the body text of the manual that you are writing. Avoid gender-specific language Pronoun constructions such as his/her or s/he do not exist. There is no need to identify gender in your instructions. Avoid culture-specific language There is little point in giving an example that everyone in your town knows about, but is a complete mystery to everyone else in the world. Avoid talking down to your reader There are few experiences more irritating for a user than documentation that says an action is easy or quick, when in fact the user cannot complete the action. Do not qualify or prejudge actions. Other parts of this guide discuss in more detail tone and language usage that can cause offense.
Grammar and Usage Guidelines Bibliographical Information This section is drawn partly from the GDSG, and partly from The Elements of Style, updated as necessary for the needs of 21st-century technical documentation writers. This section contains an alphabetical list of grammar and usage guidelines for use in &FED; documentation. Many of these guidelines are only applicable to English-language usage, refer to the American Heritage Dictionary (http://www.bartleby.com/61/) = and the Chicago Manual of Style (ht= tp://www.press.uchicago.edu/Misc/Chicago/cmosfaq/cmosfaq.html.) Abbreviations A shortened form of a word or phrase that takes the place of the full word or phrase, such as Dr., a.m., p.m., and so on. Apply the following rules when you use abbreviations: Avoid creating new abbreviations. Unfamiliar abbreviations can confuse rather than clarify a concept. Do not explain or expand familiar abbreviations. Do not include familiar abbreviations in the glossary of your manual. For abbreviations of phrases, such as i.e. for "in other words" and e.g. for "for example", do not use the abbreviation. Spell out the entire phrase. Adjectives Use adjectives with caution. If an adjective is necessary to differentiate between items, then use adjectives. In all cases, test whether the phrase can stand alone without the adjective. Acronyms A term that represents a multi-word term. Typically, acronyms are formed in the following ways: From the first letters of each word in a compound term, for example Table of Contents (TOC). From recognizable parts of a compound term, such as GNU Object Model Environment (GNOME). Apply the following rules when you use acronyms: On the first occurrence of an acronym, spell out the full term, with the acronym in parentheses. Do not spell out the full compound for well-known acronyms, unless you think the information is useful for readers. Avoid creating new acronyms. Unfamiliar acronyms can confuse rather than clarify a concept. Write the acronym in uppercase letters, unless there is a compelling case for lowercase. Include the acronym and the full term in the glossary of your manual. Adverbs Use adverbs with caution. If an adverb is necessary to qualify the function of a component, then use an adverb. In all cases, test whether the phrase can stand alone without the adverb. Classic superfluous adverbs simply, easily, quickly. Anthropomorphism Do not apply emotions, desires, or opinions to software applications. Do not apply a sense of location or dimension to a software application. A user can not be "in" a text editor. Articles Do not use the definite article the to begin any of the following items: Manual titles Chapter titles Headings Figure captions Table captions Callouts Apostrophe Do not use apostrophes except where absolutely required Do not use apostrophes to denote possession. Do not use apostrophes to denote contractions. Do not use apostrophes to denote plurals. Incorrect: Apostrophes the Main Menu's Help option don't use the default option several SCSI disk's Correct: No apostrophes the Help option on the Main Menu do not use the default option several SCSI disks Brackets Do not use brackets [such as these] as a substitute for parentheses (such as these). Use brackets for optional command line entries. Do not use angle brackets to indicate variables in text, instead use the replaceable tag. Refer to for information about using this tag. Capitalization Capitalize in the following situations: All letters in acronyms, unless the acronym is a well-known exception Initial letter of the first word in a list Initial letter of the first word in a callout Initial letter of a key name, such as the Shift key Initial letter of a sentence Command Names Avoid starting a sentence with a command name or application name that has a lowercase initial letter. Initial letter of a complete sentence after a colon Do not capitalize in the following situations: A compound term that is followed by an abbreviation or an acronym When you want to emphasize something Variable names The initial letter of an incomplete sentence after a colon Captions Use the same rules as for headings, for all captions accompanying figures and tables. Do not put a period at the end of a caption. Colon Use a colon in the following situations: To introduce a list Before an explanation After an introduction Do not use a colon in the following situations: To introduce a figure or a table To introduce headings At the end of an introduction to a procedure Column headings Use the same rules as for headings. Comma Use commas in the following situations: To separate items in a series To separate the parts of a sentence To separate nonrestrictive phrases Instead of dashes to set off appositives With for example and similar expressions Do not use commas in the following situations: In a series of adjectives used as one modifier Between two short independent clauses Commands Do not use commands as verbs. Contractions Do not use contractions such as can't, don't, or isn't. Dash Do not use the em dash or the en dash. Use a paragraph break or a colon instead, where you want to create an introductory piece of text. If you have several items that you want to introduce, then you can use a variable list. Ellipsis Use an ellipsis in the following situations: To show that you have omitted something from a sentence To indicate a pause when you quote displayed text Fractions Follow these rules when using fractions: Use numerals for fractions in tables and in units of measurement, but spell out fractions in prose. Use a space between a numeral and a related fraction, if there is a possible ambiguity. For example: 1 1/2 instead of 11/2. If a fraction is used in a compound modifier, insert a hyphen between the fraction and the unit of measurement. Gender Refer to . Grammar Use standard American English grammar rules, refer to the Chicago Manual of Style ( = http://www.press.uchicago.edu/Misc/Chicago/cmosfaq/cmosfaq.html.) Headings Use the following capitalization rules in headings: Initial uppercase letter of the first word Initial uppercase letter for all nouns, adjectives, and verbs. All lowercase letters for conjunctions, articles, and prepositions of fewer than four letters Initial uppercase letter for prepositions of four letters or longer Initial uppercase letter for conjunctions of four letters or longer Hyphen Use hyphens in the following situations: With a numeral in a compound modifier To prevent ambiguity With some standard prefixes and suffixes. Use the American Heritage Dictionary (http://www.bartleby.com/61/= ) = for guidance In spelled-out fractions In variable names of two or more words, such as directory-name. Note: filename is an exception. Do not use hyphens in the following situations: For industry-accepted terms To construct verbs With an adverb ending in ly With numerals as single modifiers With a word that is listed as unhyphenated in the American Heritage Dictionary (http://www.bartleby.com/61/= ), = and that uses a common prefix With trademarked terms Latin terms Do not use Latin terms. Use an equivalent English term instead. Like Do not use the term like to denote equivalence or similarity. Lists Introduce a list with a complete sentence that ends with a colon. Numbers Spell out numbers in the following situations: Numbers from zero through nine unless the number is part of a measurement Approximations Extreme values such as million, but precede the value with a numeral Any number that begins a sentence A number that is immediately followed by a numeral, for example: two 10 MB files Numerals Use numerals in the following situations: The number 10 or greater Negative numbers Most fractions Percentages Decimals Measurements Units of time smaller than one second References to bits and bytes Parentheses Use parentheses in the following situations: To contain the abbreviation of a term on the first occurrence of the full term In man page references, specifically the section number Period Use a period in the following situations: To end a sentence In file and directory names In abbreviations that can be mistaken for words, such as a.m. and U.S. Punctuation Use standard American English punctuation rules. In addition to the specific points of punctuation in this section, refer also to the Chicago Manual of Style (http://www.press.uchicago.edu/Misc/Chicago/cmosfaq/cmosfaq.html= .) Punctuation in numbers Do not use a comma in numerals of four digits. Use a comma in numerals of more than four digits. Quotation marks Use quotation marks to indicate material that is taken verbatim from another source. Do not use quotation marks to excuse terms from legitimacy. If the term is not legitimate, then use another term. If you must use that term, declare the term in the glossary and make the term legitimate. See v. Refer to When referring a user to another resource, use "refer to" instead of "see", and "refer also to" instead of "see also". This differentiates from the see and seealso tags that are used in indexing. These tags create special links in the index. To be consistent throughout the document, we reserve the special words "see" and "see also" for hyperlinked index references, and use "refer to" and "refer also to" for non-hyperlinked and non-indexed references. Semicolon Do not use semicolons. Slash Except where required as part of a filename, do not use slashes "/" in your writing. The construction and/or, for example, does not exist. Use one or the other term instead. Spelling Use standard American English spelling rules, refer to the American Heritage Dictionary (http://www.bartleby.com/61/) = for guidelines. Titles For manual titles use the same rules as for headings. Units Follow these rules when using units: Use standard abbreviations for units of measurements, do not invent your own abbreviations. For further guidelines, refer to the IEEE Standard Dictionary of Electrical and Electronics Terms. Use periods for abbreviated units that might be mistaken for a word. Most standard abbreviations of units account for both singular and plural usage. Insert a space between the numeral and the unit of measurement.
Composition Tips This section contains usage tips based on situations the &FDP; editors have encountered in the past. You should read and understand these examples to improve your own documentation. The &FDP; editors welcome additional examples.
Active Voice Always use active voice, except when it is awkward to do so. The tutorial tells the user how to accomplish a task, and should give instructions clearly and concisely. Avoid using "must," "need to," and the like. These words are redundant in a tutorial, since the reader assumes you are outlining necessary steps to accomplish a task. Also avoid using "maybe," "might," and other words that indicate you are unsure about the subject matter. Your tutorial should cover a subject authoritatively. The reader should never be concerned about unknown effects of following the tutorial. Incorrect: Passive voice The yum update command must be run. You might want to run the yum update command. Correct: Active voice Run the yum update command.
Present Tense Write in the present tense. A good rule of thumb is that the words "will" and "shall" are almost never needed in describing what the user should do or see. They add unnecessary length to sentences and can confuse translators. They are also often indicators of passive voice; refer also to . Incorrect: Future tense The application will display a list of target files. A list of target files will be displayed by the application. Correct: Present tense The application displays a list of target files.
=
Narrative Voice Do not use the first person "I," "we," or "us" to refer to yourself the writer (whether including the reader or not), the &FDP;, the &FED; community, or any other group. Do not refer to users with a third person pronoun ("he," "she," or "he or she") or the word "one." It is acceptable to refer to the reader with the second person pronoun "you." Incorrect: First or third person As described in the last section, I always run up2date before configuring the Samba server. If the user needs to back up his or her files, s/he should use the tar or cpio command. Correct: Second (or no) person Refer to the section on up2date before configuring the Samba server. If necessary, users can back up files with the tar or cpio command.
Negative Words Avoid negative words when possible, since they give documentation an overly dogmatic tone. The word "avoid" is useful for this purpose. Note that contractions are often used for negative words such as don't or can't. Refer to .
Uncertainty Avoid overuse of "typically," "usually," "most of," "many," and the like. While occasional use of these constructions is acceptable, overuse reduces the authority of your documentation. The documentation should adequately cover a stock installation of &FC;. It is impossible for a tutorial-length document to cover every possible configuration scenario. Address the most common scenarios and note discrepancies only as required.
=
Redundant Coverage Avoid covering redundant material, such as how to update a &FC; system. These overarching topics may be covered in other tutorials. Writers frequently violate this guideline because they feel their tutorial is not long enough. Keep your tutorial from wandering off-topic. Instead, refer the reader to a separate tutorial whenever possible for complete coverage of that topic.
Self-referential Value Judgments Avoid statements such as "One of the most important things to do is XYZ." If the procedure is important, the reader already expects it to be in your tutorial. The converse is also true: If a procedure appears in your tutorial, the reader expects it is important. This is especially true if you use a whole section for the procedure in question. Merely state, "Do XYZ." Then elaborate as required. If the whole section concerns how to do XYZ, leave this sentence out entirely. Refer also to .
Precision of Language Use precise words for actions users should take. Do not instruct users to "go" to a selection, or "find" a menu. Incorrect: Imprecise wording Go to the Main Menu -> Foobar Find the option labeled Search Correct: Precise wording From the Main Menu, select Foobar Select the Search option Do Not Discriminate Against Non-GUI Users If you are writing about a GUI-only application, you may use "click" freely. If you are writing about an application that has a text-mode interface, use "select" instead as shown above.
=
DocBook Tips This section contains tips on how to use DocBook tags more effectively in your documentation.
Admonitions Avoid overuse of admonitions. Keep admonitions short and effective by using only the most important material inside the admonition. Move any background material required to explain the admonition statements outside the admonition. Use a short but descriptive title for an admonition. Use title case for the admonition title. Incorrect: Lengthy admonition Use <command>sfdisk</command> to check input The sfdisk command accepts a script file as standard input to set up partitions on a hard disk. Sometimes sfdisk will simply reject an erroneous input file. In other cases, it will use the input verbatim, writing an incorrect partition table to your disk. Always use the sfdisk -n command to check your input file before writing to the disk. Correct: Brief admonition The sfdisk command accepts a script file as standard input to set up partitions on a hard disk. Sometimes sfdisk will simply reject an erroneous input file. In other cases, it will use the input verbatim, writing an incorrect partition table to your disk. Check Input Always use the sfdisk -n command to check your input file before writing to the disk. Avoid punctuation in titles for sections or admonitions, except for commas only where demanded. Use a title that says something about the admonition comment, such as "Reboot Required," instead of simply using the admonition type for a title ("Note"). Follow the capitalization rules for headings in the title of an admonition.
The <sgmltag class=3D"starttag">replaceable</sgmltag> Tag If your documentation formally states a specific value will be used as a convention, do not use the replaceable tag in your text or examples.
XML Entities Use the entities provided by the &FDP;. These entities are found in the common/ folder in the fedora-docs distribution. (Refer also to .) For instance, do not use abbreviations such as "FC2." Instead, use the predefined entities "&FC; &FCVER;," which produces the text "&FC; &FCVER;."
=
=
***** Error reading new file: [Errno 2] No such file or directory: 'tutoria= l.xml' ***** Error reading new file: [Errno 2] No such file or directory: 'vim.xml' ***** Error reading new file: [Errno 2] No such file or directory: 'writing= -guidelines.xml' ***** Error reading new file: [Errno 2] No such file or directory: 'xml-tag= s.xml' Index: documentation-guide.xml =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D RCS file: /cvs/docs/documentation-guide/en_US/documentation-guide.xml,v retrieving revision 1.4 retrieving revision 1.5 diff -u -r1.4 -r1.5 --- documentation-guide.xml 17 Dec 2006 00:41:55 -0000 1.4 +++ documentation-guide.xml 3 Feb 2007 22:21:58 -0000 1.5 @@ -17,43 +17,43 @@ = - = - = - = = - = = - = = = = - = = - = = - = = --- docs-emacs-nxml.xml DELETED --- --- docs-emacs.xml DELETED --- --- docs-getting-files.xml DELETED --- --- docs-intro.xml DELETED --- --- docs-module-struct.xml DELETED --- --- docs-rh-guidelines.xml DELETED --- --- docs-style.xml DELETED --- --- docs-tutorial.xml DELETED --- --- docs-vim.xml DELETED --- --- docs-xml-tags.xml DELETED --- --===============3751451739094221629==--