[TYPO3-doc] Flow & Neos documentation on docs.typo3.org
Bastian Waidelich
bastian at typo3.org
Tue Dec 18 11:56:14 CET 2012
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
More information about the TYPO3-project-documentation
mailing list