cocoon-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Reinhard Poetz <reinh...@apache.org>
Subject Re: [proposal] Cocoon documentation system
Date Mon, 17 Jan 2005 10:33:20 GMT
Sylvain Wallez wrote:
> 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 ;-)


Isn't it france that has an institute that tries to find frech translations for 
everything that comes from other languages (e.g. ordinateur) ;-)

> 
> 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'm sure that putting resources into a hierarchy and make these hierarchy public 
is harmful. About the numbers, I would try it but if so many people are against 
them because of some, I admit, good reasons, well ... My argument is still that 
in the long run, problems will pop up - as always when you use speaking keys.

> 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.

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.


>>>> 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...

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

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.

-- 
Reinhard

Mime
View raw message