[TYPO3-doc] Reference of Typo Script

[Matthew Manderson]

> What happens when there is a crucial piece of info ina
> page comments section but not in the documentation that gets installed
> with an extension?  ITs not there and potentially never realised to
> exist - which I can say form personal experience is very very frustrating.
So true - disjointed distributed knowledge!

> Maybe these examples are the starting point of what should be collated?
> Matthew whats your though reagrding this?  I assume they - these
> comments - still exist somewhere that we could request to get them...
I wish, I have asked without expectation of a reply yet but at least to flag
awareness that user annotations tend to be very well thought out and
extremely valuable to TYPO3 users generally.

Extensions and documentation. Well one approach is that the EM does flag new
versions so if the .sxw has been updated it will at least warn your BE for
you to update the extension/docs as appropriate.

At this stage I am unfamiliar with the mechanism for insterting updated
documentation. From time to time I resubmit an updated .sxw to the author
but as yet I have not seen the doc available for download. This must partly
be down to the individual and their workload to update docs.

Ideally I would expect to pass the key so to speak and allow TYPO3 users to
make changes on the fly and trust them not to screw it up.

This is partly what the annotations do but of course, many annotations do
not make it into the docs and to some degree why should they. The docs are
struggling to be concise tutorials and references. Many annotations are
more like TSbyEX type additions rather than core and can be quite long.

If the journey from typing some useful example of TS or other TYPO3 related
snippets to the docs / annotations is too cumbersome and especially if the
result is lost or never published the motivation is lost.

We now have wiki / .sxw / online docs / lists and currently inaccessible
annotations.

I proposed an idea a while back that the paper docs contained the same
references as the online docs in such a way as urls from the paper .sxw's
could lead you straight to the online doc where you can find annotations.

I never developed it back then but perhaps if the document titles were
structured say "4.1 /tsref/conditions/" This .sxw chapter title would have
the same url as the relevant page on typo3.org ie 

typo3.org/tsref/conditions/

If presumed all documentation was structured similarly you can see how each
parent page on typo3.org would contain the necessary HMENU to navigate
quickly to the relevant detailed section found in the .sxw

Going back to the collation of information, if the old annotations can be
recovered then they already provide a lot of structured content as a
starting point.

Gaps along the way can be filled in from refined searches of the archives.

Several other non TYPO3 sites have grown up with great content so we can't
deny the search engine its role in pulling together the disparate content.

If we make sure the lists and the docs and the annotations are reliably
accessible to the search engines then this is a big step in the right
direction.

Picking up on Tylers suggestion of simpy rebuilding tsbyex then this is also
possible. The danger as I see it is 1) effort on rewriting something that
is already written 2) not flagging up that tsbyex is now a NEW document
counteracted by the fact that tsbyex2 would be yet another document to
stack on the TYPO3 library shelf.

I think the emphasis should be search first .sxw second

Matthew 

> 
> Matthew Manderson wrote:
>>>I am still a friend of user comments under each webpage.
>> 
>> +1
>> 
>> It also has the important spin off of being indexed by the search engines
>> and so easily accessible to users in the context of the formal
>> documentation.
>> 
>> 
>>>http://typo3.org/ts/datatype/gettext
>> 
>> This is a really interesting idea.
>> 
>> On this basis if documentation was xml structured both the print and the
>> typo3.org web versions could possibly be maintained from a single file.
>> 
>> Even smarter maybe the idea of allowing the edited version to be online
>> say as in the wiki format and as a printed version was required it could
>> be generated on the fly with or without the annotations. Using only XML
>> stylesheets to format the appearance for either version.
>> 
>> Good.