[TYPO3-doc] Flow & Neos documentation on docs.typo3.org

François Suter fsu-lists at cobweb.ch
Thu Dec 20 17:59:50 CET 2012


Hi Bastian,

> So could one of you give this a try and add the git Repos ([1] & [2]) to
> http://build.docs.typo3.org to see if the documentation renders nicely?

Yes, we can. Actually it had been on Martin's to do list for a while. We 
were waiting for feedback from the Flow/Neos team actually ;-)

If you look at the URLs used for the TYPO3 CMS part [1], you'll notice 
that there's not a direct "translation" of Git repository names to 
documentation URLs. This is currently managed totally manually, but we 
plan to make it into a better structure at some later point, probably in 
a database table of the Flow package.

So we need your feedback about what URL you would like. About that...

> So it would be
> http://docs.typo3.org/flow/guide/partiii/configuration.html for the
> current version (master) and
> http://docs.typo3.org/flow/1.0.0/guide/partiii/configuration.html
> for the version tagged "FLOW3-1.0.0", correct?

...more or less yes, see my explanations above. Furthermore in the case 
of Flow, it is complicated by the fact that you have what seems like 
several manuals inside your "Documentation" folder ("QuickStart", 
"StyleGuide" and "TheDefinitiveGuide"). Given our current scheme, these 
three manuals would constitute the first-level chapters of a single 
manual, which is maybe not what you want (or imagined). We need to work 
something out, I guess. Martin would probably know best and be able to 
make better suggestions than me.

> * You add an (external) script to the bottom of each page passing it a
> *unique* string for the current page (this can't be the current URI
> because that is ambiguous for the current version – maybe the URI
> *including* the version number or so)

Right, we need to take care of the missing "current" path segment. It 
might be a good idea anyway to include a canonical URL in the page, 
containing the version number (and reuse that as identifier for the JS).

> * The scripts loads comments via AJAX (e.g. from a Flow service) and
> "injects" them to the page
> [snip]
> * Otherwise a "login to comment"-link would be displayed which points to
> a (to be created) https://typo3.org/my-account/sso sub page

Sounds like a reasonable workflow. I'm sure a lot of details will need 
more working out as we go along.

> I'll experiment a bit further on the commenting thingy and try to get
> some input from the design team in the beginning of 2013. It would be
> great if one of you could try rendering the Flow & Neos docs in the
> meantime.

Will be done soon hopefully, but your feedback on the point raised above 
(several manuals in the Documentation folder) would be very welcome.

Cheers

-- 

Francois Suter
Cobweb Development Sarl - http://www.cobweb.ch

[1] http://docs.typo3.org/typo3cms/


More information about the TYPO3-project-documentation mailing list