[TYPO3-hci] Documenting Typoscript

[Irene Höppner]

> Sorting a list alphabetically has nothing to do with knowing or not  
> knowing the names of the items in the list. It has to do with being able  
> to quickly locate /known/ property names. This is particularly true when  
> the list in question spans many pages--look at the 'config' section of a  
> /printed/ copy of the TSref to see what I mean.
>
Hmmm... my printed versions always became colored - which again contained  
more informations than the alphabetical order ;-). But you are right.  
Having an additional alphabetical order would be great!

> Dictionaries, library catalogs, database records are all organized  
> according to more or less arbitrary systems, not because the organizing  
> systems are inherently descriptive of the records they organize, but to  
> facilitate retrieval.
>
TS reference is neither a dictionary nor a library... imho there is a  
difference...
Try to find a php function in this list: http://de.php.net/quickref.php  
(that would be comparable to a dictionary ;-))

I just don't believe that ordering TS alphabetically in most cases will  
facilitate retrieval - in some it will. but maybe this just has to be  
tested somehow somewhere - i might be wrong...

>> The current order is either by functionality or by most-frequently used,
>> as JoH pointed out. Maybe we need a little more grouping or otherwise
>> visual hints on where we are at a huge table.

Yes, completly agree.
>
> 'most-frequently used'? I'm sorry to disagree, but that is /far/ too  
> weak an organizational principle by which to sort a list of this type  
> /if it is the only sorting available/. Can you imagine a library or  
> dictionary sorted this way? What if the php manual were sorted according  
> to most used functions? [1]
>
I would have been faster several times searching for a function. I would  
also have been faster, if for example array-functions would be sorted by  
functiongroups (all about sorting together and all about finding together  
for instance). Because of the alphabetical order I have to read each  
function until I find the one i'm looking for - lucky, if it starts with  
a, unlucky, if it starts with z ;-). Grouping functions would give an  
additional information that increases acessibility.
Php.net is imho a great example, why alphabetical ordering is often just  
used because of no better ideas...
Nevertheless: additional alphabetical order is a great idea.

> But for TS properties in general the organizing principle currently used  
> in the tables is extremely weak and should either be improved or  
> augmented with a proper index.

+1

Greets: Irene


-- 
Irene Höppner
A.BE.ZET GmbH i.G.
http://www.abezet.de/