Additional writing guidelines

[Stuart Ellis]

On Sat, 2005-06-25 at 10:28 -0400, Paul W. Frields wrote:

> 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."

Indexing does feel slightly redundant on the HTML builds on individual
tutorials, and I've tended to index more with an eye for future-proofing
for other formats.  If/when all of the tutorials are shipped together as
part of the distribution then help viewers and document search may make
use of the DocBook index tags, and so users may not start with the ToC
and read forward as they do with the current HTML format.

> 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.

I tried this and found that I wasn't entirely happy with the result in
one tutorial, although it has worked for the other.  The problem I found
was that the information presented relies on understanding a set of
concepts that are familiar to experienced Linux users, but require
explanation for others.  By moving the concepts out of the Introduction
it was possible to present them without making the Introduction lengthy,
and allow the experienced reader to skip a clearly defined section of
the document after reading the whole Introduction.

The ideal fix for this might be to have a central document of concepts,
so we can explain "packages", "repositories" etc. once rather than in
individual tutorials.

-- 

Stuart Ellis

stuart at elsn.org

Fedora Documentation Project: http://fedora.redhat.com/projects/docs/

GPG key ID: 7098ABEA
GPG key fingerprint: 68B0 E291 FB19 C845 E60E  9569 292E E365 7098 ABEA 
-------------- 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/20050628/6ca7b616/attachment.bin