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

[François Suter]

Hi Bastian,

Nice to see you here ;-)

> 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!

It's blazing fast because it's plain HTML. We aim to keep it that way 
and enhance with JS/AJAX as needed.

> 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].

Our current rendering workflow for the official TYPO3 CMS documentation 
is to pull from the referenced Git repositories and render the ReST 
files found in sub-folder "Documentation". For TYPO3 CMS extensions we 
regularly poll the TER for new extensions, grab the OpenOffice file, 
convert it to ReST, then render it. All this still needs to be 
automated. Fabien is actively working on a Flow package to manage all 
these jobs, based on the Beanstalkd work originally done by Sebastian.

This will make it possible in the (hopefully near) future to push 
rendering requests to docs.typo3.org (instead of the server pulling 
everything).

In the case of your automatically generated ReST files, you could then 
run your script somewhere on "your" side, then call docs.typo3.org to 
fetch your ReST source. As Philipp mentioned, it would be easier if the 
automatically generated files were actually merged into a Git 
repository, as docs.typo3.org is currently designed rather to work from 
Git repositories. Of course if that isn't possible, we add specific 
processes.

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

Answered above (I think), needs to be worked out in more details.

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

Versions are represented by the file structure on docs.typo3.org. There 
are sub-folders for each version, with an Apache rule to forward to 
"current" to save users from typing the latest version all the time 
(maybe it's not exactly "current", but that's the idea).

A menu to switch version is currently missing.

> * It would be great to have commenting for (some of?) the documentation.
> [snip]
> * 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)

As I said currently all pages on docs.typo3.org are straight HTML. We 
could enhance them with AJAX. The questions with caching then would just 
be to cache the AJAX requests, if that seems necessary (in terms of 
performance).

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

As Philipp mentioned, we could ask the design team for help there. Or 
many you have some nice inspirations from around the web?

> * 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".

That raises a lot of questions and potential issues. Maybe we could 
start with comments at page-level only and use the page's URI as a 
unique identifier. Even with such a simpler structure, we would still 
need to define how we handle documentation versions (do comments follow 
a version or not).

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

I would also favor having some form of authentication and relying on the 
typo3.org SSO - as Philipp also mentioned - seems like the most 
convenient solution for community members.

Cheers

-- 

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