cocoon-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Diana Shannon <terrac...@mac.com>
Subject file naming convention
Date Fri, 03 May 2002 10:44:53 GMT
Given the goal of a clean URI space, I'm seeking your input on a file 
naming convention for Cocoon's soon-to-be-contributed How-Tos, 
Tutorials, Examples, etc. documents. My assumption is that getting this 
right on the first go-around will help to eliminate a number of 
potential problems related to internal site linking.

I started investigating this issue by reading Tim Berner-Lee's article 
on the subject (See http://www.w3.org/Provider/Style/URI.html). Tim 
makes some interesting recommendations for "good" and "bad" HTTP URIs. 
Here's a summary of what I find relevant to Cocoon:

BAD: subject/topic (e.g. install, markup, action)
REASON: too subject to varying interpretations, likely to change in 
meaning over time, need to reuse in the future

BAD: extension (e.g. .html, .xml, .pl)
REASON: delivery mechanisms will change

BAD: author's name
REASON: authorship may change over time, multiple authors

GOOD: dates (e.g. 020430)
REASON: The date when the URI is issued will not change. Helps to 
separate requests which use a new system from those which use an old 
system.

Following these guidelines, we might use some variant of:
   www.apache.org/cocoon/faqs/02050308
   www.apache.org/cocoon/howtos/02060315

Questions
1. Is this overkill for the needs of projects like Cocoon, given the 
short life of documents tied to software release cycle? Is it simply a 
matter of usability vs. longevity concerns? Tim states that it is "the 
duty of a Webmaster to allocate URIs which [he/she]  will be able to 
stand by in 2 years, in 20 years, in 200 years." Do you agree with that? 
Jakob Nielson's article on a similar subject 
(http://www.useit.com/alertbox/990321.html) projects the remaining 
useful lifetime of any domain to be a mere ten years. Do we really need 
to be concerned beyond the lifetime of a particular software release, 
particularly with time-sensitive docs like FAQs, How-Tos, etc.?

2. I assume we need to continue the use of extensions for static site 
versions deployed in environments which lack clever Apache- or 
Cocoon-based mapping mechanisms.

3. Numbers in URIs remain cryptic and uninviting to me. Perhaps I'm 
hopelessly corrupt from years of bad habits, but I *like* topics in 
filenames, for example:
   www.apache.org/cocoon/faqs/config_jboss.html
   www.apache.org/cocoon/howtos/develop_source.html

However, this approach won't work so well with docs having similar 
topics. And my dream is that we will have *100s* of docs to manage.

So my current thinking is to assume that a request like:
   www.apache.org/cocoon/howtos/02050312.html
will map to a file named
   02050312.xml
with a file naming convention based on
   <two-digit year><two-digit month><two-digit day><two-digit hour>.xml
stored in
   src/documentation/xdocs/howtos

The above assumes these contributions will be included in documentation 
that appears on Cocoon's web site. Do you agree?

Comments?

Diana


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


Mime
View raw message