cocoon-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Sylvain Wallez <sylv...@apache.org>
Subject Re: [proposal] Cocoon documentation system
Date Mon, 17 Jan 2005 10:12:12 GMT
Stefano Mazzocchi wrote:

> Sylvain Wallez wrote:


<snip/>

>>> One normaly solution is to have an english title even for 
>>> non-english pages. I dislike that, it's very anglo-centric.
>>
>>
>> Well, consider the state of Cocoon, the ASF, the opensource world and 
>> the whole IT industry: they're all anglo-centric. Would you have the 
>> same concerns if this was esperanto or interlingua rather than 
>> english (or more precisely "international english")?
>>
>> Furthermore, translations must follow the original reference docs, 
>> which is the english one. So having all language-specific resources 
>> use the same name as their english counterpart isn't a problem to me.
>
>
> fair enough and coming from a french is rather something ;-)


Hehe ;-)

But maybe I'm not the usual stererotypic french guy, which is often 
considered arrogant and egocentric. Also, if you look around you won't 
see many french people working on projects using a BSD-style license 
whereas there are plenty of them on GPL projects. I had some thoughts 
about this, and IMO an explanation can be found in the french culture 
which is more about freedom in its libertarian or anarchistic meaning 
than sharing with others. But that's off-topic...

<snip/>

>> Yeah, but Amazon is a large catalogue of things, not a documentation 
>> covering lots of different subjects from introduction to details.
>
>
> True enough.
>
> But hypermedia allows a page to reside in more than one "trail of 
> reading", while a hierarchical navigation imposes a TOC-like view, 
> which might satisfy (and feel natural to one user) but look ugly and 
> totally unfamiliar to others.
>
> I think it's the "cataloguing" part that makes writing documentation 
> so hard and that's why things like wikipedia are taking off so much 
> instead.
>
> I personally think that the problem with documentation is that there 
> are two concerns:
>
>  - writers
>  - assemblers
>
> blogs, email, wikis, all share a common paradigm: you don't need to 
> 'assemble' your thoughts, you just dump them. Other people do the 
> assembly.
>
> If you wish, this is the beauty of microcontent: massive 
> parallelization (and the reason why the web bloomed, because it 
> removed the "editing/cataloging" bottleneck.
>
> but the problem was that searching for stuff used to be a nightmare 
> (see early days of altavista). This "mare magnum" of content with no 
> apparent structure made people "get lost" very easily.
>
> This is the same feeling you have in a wiki. You have a trail of the 
> pages that you have visited, but that's useless (you have it in your 
> browser too!), you want to be able to "browse" the content, go from 
> this content to something that is relevant to you.
>
> In a book, this "relevance" was done by the author (or the editors) 
> and was placed in sequential order. Or, if not, clustered in chapters 
> or sections.
>
> What a wiki misses (even the good ones like Confluence) is such 
> "clustering" notion... something that is easy to achieve with more 
> structured system, like forrest by mean of tabs or trees of links.
>
> The problem with this approach is that there is only one way of 
> clustering: repurposing pages becomes hell (and that's why there are 
> so many broken links.. because the clustering evolves not only with 
> the content of the page, but with the surroundings).
>
> By separating the contept of writers and assemblers, not only you 
> unleash a tremendous effort in content production (as our wiki 
> showed)... but you allow this content to be "clusterized" and, hear 
> hear, *in parallel*!
>
> "Conditio sine qua non" of the above is a flat URL space.
>
> Numeric? no, not necessarely, but flat for sure.


I agree with this. Actually (and IIRC we already discussed this), it 
would be interesting for a document to exist a different URLs: the main 
and persistent one (flat space), and other ones corresponding to 
different trails or navigational trees.

We could then show in each page the permalink for the page (in the flat 
space) and the various cross-cutting trails in which the page appears. 
That way, you can navigate in the web of references from the original 
trail that led you to that page to other trails mentioning that same page.

>>> 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.
>>
>>
>> How much I dislike such sites that require me to go from the main 
>> page to go down to a particular page that I've already seen...
>
>
> Sure, but that's a usability problem of the site, not of the URL space 
> "per se".


Right.

<snip/>

>>> 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
>>>
>>>  http://cocoon.apache.org/2.2/3984948
>>>
>>> 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!
>>
>>
>> And why shouldn't e.g. 
>> http://cocoon.apache.org/2.1/userdocs/flow/continuations.html not be 
>> there?
>
>
> example: because somebody decided to split the user section by 
> "concern area" and so continuation now belongs to
>
>  http://cocoon.apache.org/2.1/users/programmer/flow/continuations.html
>
> but not everybody thought that this was a good idea, so we have a 
> redirect from the old URI to the new one... but down the road, 
> somebody from the Lisp world come along and shows how the term 
> "continuation" is actually misleading and he convinces to change this 
> to "webcontinuations" so that we now have a redirect from the old URL 
> to the newer one to the newest one.
>
> But it's true that persistenace of a URL is a property of those 
> administering it not of the URL itself.


Right. And maintaining a set of redirect rules for years is likely to 
become a nightmare ;-)

>>> let's be brave!
>>
>>
>> Let's be brave and dive into a fog of meaningless URLs? I'm not 
>> convinced...
>
>
> I showed why I want a flat URL space.
>
> Now, I could be convinced to change from
>
>  http://cocoon.apache.org/2.2/3940834
>
> to
>
>  http://cocoon.apache.org/2.2/continuations
>
> but only if we mandate that titles cannot contain '/'. This will force 
> people to test for URL naming collisions and will carve a 
> anglophone-centric view of our system (for now and forever!), but I 
> can live with that.

> thoughts?


Well, the need for multiple trails that can evolve over time clearly 
leads to some kind of permalink in a flat space. Now can we really use 
distinctive names for all pages in a flat space? Wikipedia tends to say 
that it is possible, but at the same time, the content of the Cocoon 
docs is different from Wikipedia in that Cocoon is likely to provide 
several pages for a single concept whereas Wikipedia only has one. Thus, 
finding names may not be scalable enough...

Mmmh...

Sylvain

-- 
Sylvain Wallez                                  Anyware Technologies
http://www.apache.org/~sylvain           http://www.anyware-tech.com
{ XML, Java, Cocoon, OpenSource }*{ Training, Consulting, Projects }


Mime
View raw message