Additional writing guidelines

[Paul W. Frields]

On Tue, 2005-06-28 at 14:32 -0700, Karsten Wade wrote:
> On Tue, 2005-06-28 at 19:21 +0100, Stuart Ellis wrote:
> > 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.
> 
> As much as I cringe at it whenever I do it, I do think there is some use
> in having an indexing term that closely resembles the section title.
> This may help with Google ratings, and as Stuart points out, it helps
> make documents more modular as the project grows.
> 
> I think the key is that doing the close resemblence indexing is less
> than a bare minimum.  There needs to be more meaningful indexing, as
> well.
> 
> For example, I've been using "how to" and "what is"/"what are" whenever
> a section addresses something like that.  This can build quite an
> impressive list in the index.

Yeesh.  Well, I will yield graciously if outvoted on this one... I will
also make an effort to back out my CVS changes on the yum tutorial on
which I've been working, to restore those <indexterm>s.

> > > 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.
> 
> I think you are both discussing slightly different things and are not
> that far from agreement.
> 
> The main focus of a document should be on one or a few closely related
> technologies.
> 
> It seems reasonable to cover any additional concepts that need
> explanation to help support the overall topic.
> 
> For example, an Apache PHP Tutorial might include various pieces about
> how to update httpd.conf without explaining everything about that conf
> file.
> 
> A guideline might be, if a topic threatens to grow from a <section> to a
> <chapter> and the topic is mainly out of scope for the document, it
> deserves its own document and a reference.
> 
> I like the idea of moving content to separate background/concept
> sections for skipping by the knowledgeable.

Like Karsten says, we actually agree on this more or less.  It's
difficult right now to split out those concepts sometimes -- for now --
because we currently have a paucity of material to which we can refer
readers.  Part of the growth of the project will be demonstrated in how
often we can pare down our tutorials since material is covered better
separately, like for instance being able to refer people to a Bugzilla
Tutorial to file bugs. :-)

> > 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.
> 
> Good idea.  We could have a standard section of references, customizing
> it per document for whatever external concepts might need better
> understanding.

We currently have a jargon-buster that could stand some juicing up... it
might make an ideal place to put some explanatory material.  What say
you guys?

-- 
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: signature.asc
Type: application/pgp-signature
Size: 189 bytes
Desc: This is a digitally signed message part
URL: <http://listman.redhat.com/archives/fedora-docs-list/attachments/20050628/0514c7ef/attachment.sig>