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 .
rpm-info.xml (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 Makefile
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.
DOCBASE
This variable contains the name for the main (parent) XML
document. Follow convention by naming your document after the
module name.
PRI_LANG
This variable contains the ISO code for the original
version of the document, such as
en_US.
OTHERS
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.
DOC_ENTITIES
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.
XMLFILES_template
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 rpm-info.xml
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 rpm-info.xml 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:
html
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.
html-nochunks
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.
pdf
This target builds only the PDF document
for all document languages. PDF production is
currently erratic and may not work for your document.
tarball
This target builds only the tar(1)
archive for all document languages.
all
This target builds all targets listed above.
clean
This target deletes any temporary, or generated files, but
does not erase any HTML,
PDF, or archive files.
distclean
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 sfdisk 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 replaceable
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==--