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

[Bastian Waidelich]

Bastian Waidelich wrote:

> Now we'd love to finally move the documentation of Flow & Neos to
> docs.typo3.org [...]

Thanks a lot for your detailed replies!
So, let me quickly rephrase (to see whether I got everything right):

> * What would be the next step in order to get Flow (and Neos)
> documentation to docs.typo3.org "as is"?

This should be already possible according to your current workflow.
The documentation of Neos and Flow are in their respective git 
respositories in ReST format and we take care of updating that on a 
regular basis (the script we use to generate references and such is not 
of interest for this workflow as we're taking care of executing the 
script and pushing the generated result to git regularly as well).

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?

If that's the case we could already replace 
http://flow.typo3.org/documentation by http://docs.typo3.org/flow/ 
(preferably with some redirect rules to keep the old URIs working).

This would be awesometastic!


> * Do you have a plan regarding "versioning" of the documentation?

You use git tags for versioning, perfect.

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?


> * It would be great to have commenting for (some of?) the documentation.

You use static HTML files to render the docs, so progressive enhancement 
would be the way to go.

I could imagine a workflow like this:

* 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)

* The scripts loads comments via AJAX (e.g. from a Flow service) and 
"injects" them to the page

* A comment should probably contain following details:
   * dateTime
   * body
   * sender (e.g. email/TYPO3 username & maybe profile image)

additionally we could add a field "data" that contains arbitrary 
key/value pairs. With that in place we could implement commenting on 
certain sections on the client-side.

* The script also retrieves the currently logged-in user. This is where 
it gets a bit tricky. We could use the existing SSO mechanism to 
authenticate a TYPO3 user to the comment service. But then we probably 
need to synchronize all users as we currently do for the T3CON sites..

* If a user is logged in, the script would also render the comment form 
(respectively inject the markup to a hidden modal and add links to each 
section to comment on it)

* Otherwise a "login to comment"-link would be displayed which points to 
a (to be created) https://typo3.org/my-account/sso sub page


Ok, this turned out to be a bit more than a *rephrasing*, excusé ;)

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.

All the best,


[1] 
http://git.typo3.org/FLOW3/Packages/TYPO3.TYPO3.git/tree/HEAD:/Documentation
[2] 
http://git.typo3.org/FLOW3/Packages/TYPO3.FLOW3.git/tree/HEAD:/Documentation

-- 
Bastian Waidelich
--
Core Developer Team

TYPO3 .... inspiring people to share!
Get involved: typo3.org