Additional writing guidelines

[Stuart Ellis]

On Tue, 2005-06-28 at 18:25 -0400, Paul W. Frields wrote:
> 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.

I'd be happy to go as far as indexing Guides only, and have no indexing
at all for tutorials until it really becomes important.  The main thing
is making a conscious decision for all documents and running with it
until circumstances change.


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

I've been thinking around this issue for a while, although I wanted to
get the existing tutorials out first.

One problem with the current Jargon Buster is that it is open-ended -
there are no rules are to what ought to be defined and what ought to be
left to Wikipedia.  

This is perhaps fixable by having a set of guidelines as to what should
be glossaried, and then making sure that the entries are written.  (This
is actually an offer of work: I would be willing to take this on).

A separate issue is that the glossary format is more terse than
explanatory - I don't think that the four paragraphs on repositories
currently in the yum tutorial could be replaced entirely with a glossary
entry.

Perhaps we could have some canned concepts paragraphs and drop them in
each document (as Karsten says), or even perhaps use includes from a
bank of XML fragment files (about-packages.xml, about-mirror-sites.xml).

Another approach would be to take the bull by the horns and write an
orientation guide to ensure that users have a baseline understanding
that we can assume for other documents.  That would require some careful
scoping, so that it just teaches them how to fish, without getting into
trying to document every task.

-- 

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: 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/20050629/0108f544/attachment.sig>