Re: Shortened titles in OMFs and Yelp

[Eric Baudais <baudais kkpsi org>]

I'd like to explain a little bit of the history and my reasoning in
rejecting this idea of either adding a second title or replacing the
title with a shorter version.

The GNOME documentation used to have somewhat short titles before GNOME
2.0.  The titles used to be like "Gedit."  This all changed for GNOME
2.  Why did it change?  I believe that the change came as a result of a
discussion about what types of information should be displayed on the
title page and what information should be displayed on the TOC page. 
There were recommendations for including the author, version,
maintainer, and title at the top of the TOC.  This was rejected by Pat. 
He said, "I'm not saying that the above information is not important, on
the contrary it is vital, but it is meta-information that is aimed at a
different audience than the user."  This vital metadata was put into a
separate title page which came about with contributions from everyone. 
This may not seem very important, but then the titles got bigger from
the examples in both the templates and the sample title page.  Character
Picker Applet Manual V0.2 became the title for the sample title page and
the templates produced MY-GNOME-APPLICATION Manual V2.0.  The titles
were making up for the loss of information in the first page the user
views (TOC page).  This has resulted in large titles which Yelp cannot
handle.  Is the solution to add some more metadata?

On Mon, 2002-07-15 at 12:28, Dan Mueth wrote:
> 
> On Mon, 15 Jul 2002, Eugene O'Connor wrote:
> 
> > So it's OK to use, for example: 
> > 
> >    <title>
> >      Calculator
> >    </title>
> > 
> > until the shorttitle attribute is implemented? 
> 
> Yes.

Yes, this is a very good idea.  The title of a document should be short,
sweet, and to the point.  This problem of cancerous titles which grow
and grow without bounds should be ended.  I would also suggest to make
the title of the Calculator documentation just "Calculator".  The
metadata should describe the type of documentation, the version, the
authors, and the license. Therefore there needs to be two changes made. 
The first change to the OMF file to shorten the title and the second
change to the documentation to alter the title to the shortened title
within the OMF file.

> > The contents of the OMF <title> tag do not have to match the contents of
> > the XML <title> tag? If that's the case, perhaps we can use the original
> > suggestion so that we can easily update the OMF files when the 
> > shorttitle attribute is implemented. The original suggestion was:
> > 
> >   <comment>
> >      GNOME Calculator Manual V2.0
> >    </comment>
> >    <title>
> >      Calculator
> >    </title>
> > 
> > What do you think?

I don't like this.  With the title of the documentation being
"Calculator" the comment tag is redundant.  It describes information
that is already in the metadata.

1) GNOME is in the category.  The category already classifies the
documentation and you don't need to repeat that classification.

2) Calculator is in the title.  It is the title of the documentation and
should not need to be restated here.

3) Manual is in the type.  The type metadata already describes the type
of documentation.  Again repeated information.

4) V2.0 is in the version.  The version metadata describes the version
of the document along with the date and a short description.  Also
repeated information.
 
> I like the idea of preserving the original title in the OMF file as a 
> comment so that the OMF files can be easily updated later.  However, 
> <comment> is not a valid OMF element.  So, an OMF file which looks like 
> the above will not validate and the document will not be registered with 
> ScrollKeeper :(

Scrollkeeper shouldn't have to break the OMF specification.  The
metadata should describe the document as fully as possible, but without
repeating or stating the information in another way.  I believe that the
OMF specification has done that and should not be changed at all.  Also
any changes should be questioned thoroughly as to there need.  A couple
questions should be asked when contemplating a change:

1) Does this tag describe new information not already in the other tags?

2) Does this tag information which is useful to all the documents?

With all that I'd like to propose that the GDP shorten the titles in the
documentation which contain redundant information.  The information
taken out of the titles should already be contained in either the
metadata or the title page.  The title changes in the documentation
should propagate to the OMF files and the titles in the <title> tag
should be appropriately changed.

Eric Baudais