cocoon-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Stefano Mazzocchi <>
Subject Re: [proposal] Cocoon documentation system
Date Sat, 15 Jan 2005 19:27:27 GMT
Reinhard Poetz wrote:
> Stefano Mazzocchi wrote:
>> David Crossley wrote:
>>> Stefano Mazzocchi wrote:
>>>> Bertrand Delacretaz wrote:
>>>>> Reinhard Poetz a ?crit :
>>>>>> At I 
>>>>>> propose the architecture of a new extensible documentation system...
>>>>> Thanks Reinhard - to me this looks really good, and the fact that 
>>>>> you're backing your proposal with actual work makes all the 
>>>>> difference ;-)
>>>> Touche'.
>>>> I've tried with Doco but I never put it up with the expectations :-(
>>>> What can I say: go for it!
>>> Well, some of the ideas and discussion from Doco would evolve
>>> into this system. Thanks for that much, it all helps.
>> Glad to hear that.
> Yep, your proposal and the discussions helped a lot :-)
> ... and not to forget over the last 10 days, Upayavira helped me with 
> many talks.
>> I have only one problem with Reinhard's approach: open editing.
>> And not because I fear defacing but I do fear link spamming bots.
>> Please, do not leave the comments open for non-humans or it's going to 
>> be hell over again (at the very least let's use captchas)
> good point.
> I also want that every comment (not only doc changes) has to be approved 
> by a committer. So we have a double-barrier (hope that's understandable 
> English) for spamming bots.

Ok, captchas + human moderation is clearly too high of a barrier for 
spammers and even for defacers. Even infra@ would not have a problem 
with that.

> Two question to Stefano (and everybody else): I proposed numbers as 
> document IDs? What do you think about this?

I used to be a fanatic of 'readable URL'... but I think they present 
more problems than they solve.

First of all, the encoding is a pain. It's fine for english, but until 
we ave IRI (internationalized resource identifiers, think "unicode meets 
URI") support forget chinese, japanese, cyrillic, hebrew, korean and so on.

One normaly solution is to have an english title even for non-english 
pages. I dislike that, it's very anglo-centric.

Second, people like Nielsen argue that readable URLs are easier to use 
and to remember. I think it's bullshit. Not even my bookmarks satisfy me 
anymore in terms of link management ( + google killed my 
browser bookmarks), do you really think I would type in or remember any 
URL today? nonsense.

There are a few values of a readable URL. The first is actionable 

So, if you find yourself in

you can automatically infer something like > a > b > c > d > e > f > g

and, for shitty web sites, that is a *tremendous* navigation help. For 
URLs like

that's it, there is no hierarchical context that you can infer from it.

Now, we will not have a shitty web site, so this argument doesn't apply 
and Amazon (which is the most used e-commerce site in the world *and* 
has the worst URL space ever imagined!) shows that URL-space design does 
not impact usability, if the pages don't require so.

Actually, since geeks are used to hack into URLs but normal people do 
not, having a flat or bad URL space forces usability people to think 
about navigation in the page and not outside.

Another argument, and probably more important, is that a flat URL 
structure gives a sense of 'wikiness' that people have come to dislike.

Now, again, this is a false impression (inspired by a plethora of bad 
practices rather than effectual technological limitations) but a strong 
one nevertheless (I do feel the same about it at times).

But *exactly* because of that, I think we should be brave and show the 
world that a flat URL space *does not* automatically yield 'wiki-like' 
flat spaces that are extremely painful to navigate.

Flat numeric URL spaces have also extremely interesting advantages:

  - pages can have their titles adjusted without impacting persistance 
(links are more solid over time)

  - pages can be rearranged/repurposed/re-aggregated/re-used without 
impacting persistance

> Another question is the structure of URLs - the new efforts of Sylvain 
> who wants to provide some docs in French needs some thinking where to 
> put them. I propose
> http://c.a.o/  ............... editable global docs (own repository)
> http://c.a.o/fr/ ............. editable global docs in French (own 
> repository)
> http://c.a.o/2.2/ ............ editable docs of 2.2 (own repository)
> http://c.a.o/2.2/fr/ ......... editable docs of 2.2 in French (own 
> repository)
> http://c.a.o/2.2.1/ .......... "frozen" docs of the 2.2.1 release
> http://c.a.o/2.2.1/en/ ....... "frozen" French docs of the 2.2.1 release

I don't think we should have frozen docs at any time, they are included 
in the distributions anyway and those distributions will be persisted 
for the longest time.

Sun did this with the Java API did this and created a mess, people 
linked to java/1.4.2/ and then 1.4.3 was created and all links broke down.

If a document shipped in 2.1.3 has a bug and was fixed in 2.1.4, why 
would anybody want to see it? and if 2.1.4 removed something useful for 
2.1.3, that's a bug and we should fix it in the doc, rather than make 
everything available on the web.

So I'm -1 on this.

As for french docs, I *strongly* think that we should do this thru 
content-negotiation rather than URL design. A person accessing the page 
with a french browser will get the page in french, that's all they have 
to know (and the page will have a series of flags that will trigger an 
overload in locale, but that's going to be a parameter of the URL, not 
part of it).

The language a page is written, just like the data-type of the page, 
should not belong in the URL.

This makes the URL space way more "solid" overtime: I can link to

and *be sure* that it will be there a few years from now and, by then, 
maybe a translation in my native language would have poped up!

let's be brave!


View raw message