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

[Bastian Waidelich]

Hello dear documentation team,

first let me tell you how much we all appreciate all the work you guys 
to on the documentation front, http://docs.typo3.org/ already looks very 
promising and it's blazing fast!

As you know the Flow documentation currently resides on 
http://flow.typo3.org/documentation.html – We wrote a little script that 
creates reStructuredText files from PHP code to generate references (for 
Fluid ViewHelpers, Flow Validators, TypeConverters, Annotations and such).
Another script renders these rst files and imports them to the TYPO3CR 
under a certain node path to be rendered on the Flow homepage [1].

Now we'd love to finally move the documentation of Flow & Neos to 
docs.typo3.org and I have some questions about the required steps to 
take and about some features we'd like to have in the documentation.
I found some notes of a previous meeting regarding this [2]. 
Unfortunately I couldn't join that meeting and I'm not sure about the 
current status. So please bear with me in case I repeat topics that are 
already resolved or obsolete in the meantime:

* What would be the next step in order to get Flow (and Neos) 
documentation to docs.typo3.org "as is"? Can we somehow integrate our 
little script to generate automatic references?

* Do you have a plan regarding "versioning" of the documentation? We'd 
need to be able to switch between 1.x and 2.x documentation for 
instance. Besides it would be great to have some kind of "last changes" 
section to see whenever content has been added/changed.

* It would be great to have commenting for (some of?) the documentation. 
I started to work on a generic commenting widget based on Flow & Fluid a 
while ago. The idea was to have a similar functionality as on github 
pull requests: a user can comment on any section of a document. Next to 
the section could be some indicator on how many comments exist for it. 
If one expands them they can be inserted directly underneath the 
corresponding section in chronological order. In a first draft this 
worked quite nicely, the widget is inserted below the "static" 
documentation and injects loaded comments to the document via javascript.
The problems & missing things are:

  * Caching: We use Flow to render the page and varnish currently 
prevents caches everything with the gloves off (we could purge the cache 
for new comments but I didn't get around this yet)

  * Design: A static example on how to include the comments in a nice, 
not too distracting but obvious way would be very helpful

  * Versions: The current idea is to bind a comment to the page and 
unique anchor (= id) of a section. What if the section id changes or the 
content has been changed after a comment was made? Maybe we could make 
the comments "editable" by us so that we could (re)move comments in case 
they're "lost".

  * Authentication: I'd suggest to use (a slightly modified) version of 
the Single Sign-On script we use for the conference websites in order to 
have authentication in place. The alternative would be an "open" form of 
course but I'm not sure what that means spam- and (anonymous) shitstorm 
wise ;)


All the best and thanks again for the great work so far!


[1] http://git.typo3.org/FLOW3/Packages/TYPO3.DocTools.git
[2] https://notes.typo3.org/p/DocTeam-FLOW3%20Meeting

-- 
Bastian Waidelich
--
Core Developer Team

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