cocoon-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Stefano Mazzocchi <stef...@apache.org>
Subject Re: [proposal] Cocoon documentation system
Date Mon, 17 Jan 2005 19:36:58 GMT
Reinhard Poetz wrote:

> Look at http://apache.org/~reinhard/cocoon/2.2/1.html. The navigational 
> structure is hierarchically organzied but not the files (only 1.html, 
> 2.html and 17.html are working). I don't see the value of having the 
> hierarchies in the URL.

no, but I somehow agree with Sylvain that it looks somewhat, hmmm, 
wiki-like to have those numbers... for example, Daisy does this and my 
understanding is that that people complained about.

Steven, can you give us some feedback on how things went over at Daisy 
with the flat numeric URL space?

> Yes, another reason for numbers so that we do not end in docs like
> 
> http://cocoon.apache.org/2.2/flowscript
> http://cocoon.apache.org/2.2/flowscriptInJava
> http://cocoon.apache.org/2.2/flowWithJavascript
> http://cocoon.apache.org/2.2/flowscript-api
> http://cocoon.apache.org/2.2/flowscript-overview
> http://cocoon.apache.org/2.2/flowscriptIntrocution
> http://cocoon.apache.org/2.2/flowscriptIntrocution

typos in the URLs! that's a good one :-)

> I know that's the job of us committers who approve new docs and can find 
> better names, but over the time (thinking in years) I fear that we end 
> in a mess because it will not be very easy to keep oversight.

well, ok, I use numeric URLs for my linotype URL space and I have to 
tell you that I'm not dissatisfied. First of all, they tend to be 
smaller, therefore easier for people to send into emails. Second, they 
have a sort of neutrality and makes people curious.

For example, take a look at

  http://www.betaversion.org/~stefano/linotype/news/57/

[note that I think that news/57 is wrong, should be 57 and I'm working 
on migrating all my content to a new URL scheme!]

The other problem is that people tend to think that

  http://www.betaversion.org/~stefano/linotype/news/57/

and

  http://www.betaversion.org/~stefano/linotype/news/57

are the same URL because most web servers do that translation 
automatically (which is *WRONG*, but you can't undo history)... as a 
result, I have to perform permanent redirects explicitly to avoid silly 404.

If I used a title-based URL, the above would be

http://www.betaversion.org/~stefano/linotype/news/A_No-Nonsense_Guide_to 
_Semantic_Web_Specs_for_XML_People_%5BPart_I%5B

which not only would be long and hard for people to read, but it would 
also be really ugly with those %xx escaped entities

But on the other hand, the URL identifier and the document title don't 
need to be exactly the same, so I could create a new field that says 
"URL title" and I would have had something like

http://www.betaversion.org/~stefano/linotype/news/Semantic_Web_Guide_Part_1

which is more reasonable.

this is, in fact, similar to how wikipedia does it and they have half a 
million pages and growing exponentially.

There is something interesting to say about wikis: the fact that the 
notion of "links" is so embedded and the URL space so flat, makes it 
easy to get "collisions".

if you wish, a wiki URL space is not different from a folksonomy's tag, 
where you get collisions that sometimes could be bad, but most of the 
time are userful.

Case in point

  http://en.wikipedia.org/wiki/Cocoon

"This is a disambiguation page — a navigational aid which lists other 
pages that might otherwise share the same title. If an article link 
referred you here, you might want to go back and fix it to point 
directly to the intended page."

Lovely.

There is a lot to learn from Wikipedia... but one thing that they are 
missing: trails.... paths that guide the user to a given set of pages to 
learn a particular topic (see the java tutorial for a fine example of 
such a style... java's success is, I believe, partially due to that!)

We could even use Wikipedia directly as our documentation infrastructure 
and forget about our own!

http://en.wikipedia.org/wiki/Apache_Cocoon

Anyway, the more I think of it, the more I think it makes sense to 
follow the URL model of Wikipedia.

-- 
Stefano.


Mime
View raw message