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

Philipp Gampe philipp.gampe at typo3.org
Tue Dec 18 13:51:14 CET 2012


Hi Bastian ,

Bastian Waidelich wrote:

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

+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:

I appreciate your efforts towards integrating the documentation of Flow and 
Neos into http://docs.typo3.org/
I was not able to join the meetings lately, but I will try to give you a few 
answers, especially where you ask for feedback and comments.

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

That depends a little on the workflow.

There could be a pre-render script that is executed before the actual 
rendering to update the automatic generated part of the documentation.

It might be easier of the script is run every night and just commits to the 
corresponding repository. That way, it would be independent from the 
rendering.

Or we could try to use our to-be-build automation/jobqueue server and 
trigger the next run of a doc update whenever a commit touching the relevant 
folders is made.

This depends a little on your needs.

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

AFAIK the current status is to have an independent documentation of each 
version and switch to select an older version.

Technically this will be solved with git branches. The exact visual 
representation on the website is still open.

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

That sounds great.

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

We thought - a year ago:) - about late AJAX binding for the comments, so 
that the documentation is rendered fast form static files and then the 
comments are loaded later to enrich the website.

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

Design team ?!?

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

Comments must of course be editable via an admin interface.
A form to change the section of all comments from a specific section might 
be needed, but should not be too hard to build.

And comments would need some kind of vote system, so that the most helpful 
comments can be displayed on top.

>   * 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 go with SSO to typo3.org.
 
> All the best and thanks again for the great work so far!
+1

Best regards
-- 
Philipp Gampe – PGP-Key 0AD96065 – TYPO3 UG Bonn/Köln
Documentation – linkvalidator
TYPO3 .... inspiring people to share!



More information about the TYPO3-project-documentation mailing list