[TYPO3-doc] Reference of Typo Script

[Tyler Kraft]

Poor poor Peter... I bet he never thought his off the cuff bit of 
frustration would end up being discussed like this ;-)



Matthew Manderson wrote:
>>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.
> 
>