tracks/titles [was: Re: --- Help with document classification ---]

[Diana Shannon <te...@mac.com>]

On April 26, 2002, Bertrand Delacretaz wrote:

Very helpful comments, Bert.

> 1) Tracks:
> it might be worthwile at some point to create "tracks" into the
> documentation, task-oriented reading guides.
>
> For example: if you want to publish static XML to HTML, here's your 
> reading
> list: "FAQ 232, FAQ 321, html publishing how-to, site navigation guide"

Do you think these need separate classification, or should they be 
how-tos (with links to other how-tos), categorized as tracks?

>
> 2) Master of the Titles:
> Document names/titles (and their consistency) are sooo important IMHO to
> guide the user to the right place, I think the main title of every 
> document
> should be reviewed by the community or by a designated "Master of the 
> Titles"
> before publishing the document.

What if we also added a one-sentence description of the piece, along 
with title and last modified date, to be returned with search results?

Diana


---------------------------------------------------------------------
To unsubscribe, e-mail: cocoon-dev-unsubscribe@xml.apache.org
For additional commands, email: cocoon-dev-help@xml.apache.org

Re: tracks/titles [was: Re: --- Help with document classification ---]

[David Crossley <cr...@indexgeo.com.au>]

Diana Shannon wrote:
> Bertrand Delacretaz wrote:
> 
> > 1) Tracks:
> > it might be worthwile at some point to create "tracks" into the
> > documentation, task-oriented reading guides.
> >
> > For example: if you want to publish static XML to HTML, here's your 
> > reading
> > list: "FAQ 232, FAQ 321, html publishing how-to, site navigation guide"
> 
> Do you think these need separate classification, or should they be 
> how-tos (with links to other how-tos), categorized as tracks?

Sounds like a separate class of document. I wonder if
this is an application of XML Topic Maps (XTM) ... of which
i know nothing about ... just fascinated by their possibilities,
and Cocoon is the perfect place to implement them.
TopicMaps were briefly discussed recently on Forrest-dev.
http://marc.theaimsgroup.com/?l=forrest-dev&m=101647290524645

> > 2) Master of the Titles:
> > Document names/titles (and their consistency) are sooo important IMHO to
> > guide the user to the right place, I think the main title of every 
> > document
> > should be reviewed by the community or by a designated "Master of the 
> > Titles"
> > before publishing the document.
> 
> What if we also added a one-sentence description of the piece, along 
> with title and last modified date, to be returned with search results?

I agree with Bertand that the Titles of all documents need to
be carefully reviewed. They are the most important part of the
document. At the organisation that i worked with when the WWW
first hit the scene, i wrote applications that automatically pestered
people if they did not properly utilise <title> in their HTML.

Until recently there was a problem in Cocoon whereby the
space available for a title was limited. This was because
Cocoon was showing off with banner-image generation
which meant that only short titles could be used. This would
have had a massively detrimental effect on the quality of
document titles. Now that we have plain-text banners, we
can return to more descriptive titles.

Well-spotted, Bertrand. The documentation review needs to
have this as a specific task - generate a list of all current
titles and review them.

--David

---------------------------------------------------------------------
To unsubscribe, e-mail: cocoon-dev-unsubscribe@xml.apache.org
For additional commands, email: cocoon-dev-help@xml.apache.org

Re: tracks/titles [was: Re: --- Help with document classification ---]

[Bertrand Delacretaz <bd...@codeconsult.ch>]

On Friday 26 April 2002 11:19, Diana Shannon wrote:
>. . .
> Do you think these need separate classification, or should they be
> how-tos (with links to other how-tos), categorized as tracks?
>. . .

I see the tracks as part of the navigation, which could be:

a) search-based ("googling through the docs") 
b) track-based ("what do you want to study")
c) document-type based ("faqs", "guides", etc.)

In this view tracks documents are orthogonal to the rest of the 
documentation, so yes, a separate classification. 

Either there are "tracks" XML documents that point to other docs and need to 
be properly maintained, or (parts of?) documents that need to be included in 
a track contain attributs like

<belongs-to-track track-name="html-publishing" chapter="intro" 
position="250"/>

Where position is a relative ID used to sort the document when creating the 
track.

>. . .
> What if we also added a one-sentence description of the piece, along
> with title and last modified date, to be returned with search results?
>. . .

Certainly useful, but the "official document names" are very important IMHO 
so that the user knows what is what. 

-Bertrand

---------------------------------------------------------------------
To unsubscribe, e-mail: cocoon-dev-unsubscribe@xml.apache.org
For additional commands, email: cocoon-dev-help@xml.apache.org