Additional writing guidelines

[Paul W. Frields]

As a ramp-up to working on the DocGuide, I am catching up on some
editing.  As I do so, and at the risk of sounding pedantic or picky, I
wanted to share some thoughts with the list.  I've been dipping into a
bunch of the languishing tutorials and only doing real work on one or
two, so I'm not going to point out specific examples, especially since
that might be construed as unfair criticism of a particular work.  The
fact that there is any material at all to edit is a BIG credit to the
hard-working volunteer writers who provided it.  

I hope these thoughts might be helpful to some of the people who have
come on board recently and are preparing ideas for future tutorials.
Comments and discussion are welcome.

You may wish to refer to and comment on:

http://fedoraproject.org/wiki/DocsProject/DocumentationGuide


1.  Organization:

All tutorials and guides should have an introduction.  All tutorials
should follow the introduction content standards listed on the wiki.
Remember that tutorials are *task-oriented*, and not meant to be
lectures reduced to XML.  Constantly ask yourself:  "What are the
objectives of this tutorial?  What will the user BE ABLE TO DO after
reading it?  Is what I'm writing fulfilling those objectives?  Does it
show them what to do?"

2.  Indexing:

Be mindful of the difference between good sectional organization and
indexing.  The table of contents should suffice to locate major and even
minor topics, *if* the material is organized correctly.  An index is
used to locate concepts and terms whose location isn't obvious from the
table of contents or the organization of the document.

There may in fact be no need to index a short tutorial, which can be
read in its entirety quickly.  Indexing is more important for longer
works that a reader is not expected to digest in one sitting.  Indexing
can still be good in a smaller work as long as it is used judiciously.
There is no need to be concerned about indexing every topic that appears
in a section.  Do not index redundantly against the table of contents.
If you have a section that entitled "Using Application XYZ," you should
not make an index entry for "XYZ, using."

You should expect all readers will read the Introduction section of the
tutorial, even if that is not always the case.  Technical writers and
editors, just like mathematicians or programmers, must at some point
rely on a few basic postulates.  A programmer rightly expects that if
you use his code, you will read the licensing terms, and the function
headers.  We expect that someone who locates a tutorial will read the
introduction to see that it matches the subject material.  Therefore
indexing material that should be found in the Introduction is redundant
and unnecessary.

Keep in mind that the Introduction should include a section for each
major technology discussed in your tutorial.  A tutorial should not have
more than two or three major technologies involved, or else you should
consider splitting it.

3. The Dreaded "Core Dump":

Be wary of using terms with which a new user is not necessarily
familiar, if your target audience includes new users.  (Your target
audience should be defined in the Introduction as required above.)
Always write to the level of the *least* experienced user whom you
reasonably expect to use your document.  Remember that bytes are cheap,
and if an explanation requires an extra paragraph, you should write it.
See the "References" section below for a different take.

A consistent problem with documentation is that it can easily become
what my coworkers and I frequently refer to as a "core dump," in the
sense that it is an unstructured output of all of the author's (many
times considerable) knowledge of a subject.  Be wary of this in
writing/editing documents.  "Core dumps" are not good documentation, and
lose their authority quickly for discerning readers.

The best way to avoid core dumps is to OUTLINE your document before you
begin, as most of us did for composition classes as {pre,}teenagers.
Flesh out your outline, and revisit it several times *before* you begin
writing.  Do the ideas progress logically?  Are you fulfilling
"dependencies" in the education process by discussing the basics first,
before you move on to more complex material?  Put yourself in the shoes
of your least experienced reader.  (If you are unable to remember a time
when you were inexperienced, you need to find someone new to the subject
to review your document and give you pointers!)

4. References:

Using references to other authoritative documents is a good thing.  An
authoritative document might be another approved FDP tutorial or guide,
an official work of the Linux Documentation Project, or a published work
(of the dead-tree variety, including online offerings of dead-tree
works).  Messages on listservs, online forums, news sites, or other
sources that do not have a rigorous editorial process are not good
references.

- - - - - 
Well, that's it for now.  Maybe more later when I have a chance to pore
over some of the other stuff in CVS.  Have a great weekend!

-- 
Paul W. Frields, RHCE                          http://paul.frields.org/
  gpg fingerprint: 3DA6 A0AC 6D58 FEC4 0233  5906 ACDB C937 BD11 3717
 Fedora Documentation Project: http://fedora.redhat.com/projects/docs/
-------------- next part --------------
A non-text attachment was scrubbed...
Name: not available
Type: application/pgp-signature
Size: 189 bytes
Desc: This is a digitally signed message part
Url : http://lists.fedoraproject.org/pipermail/docs/attachments/20050625/7a9e02bc/attachment.bin