[TYPO3-doc] [resST migration] FLOW3/Documentation teams meeting

[François Suter]

Hi all,

Today we had a joint meeting between members of the FLOW3 and 
Documentation teams. There were two main goals:

1) check that we are still sync with regards to documentation, since the 
whole migration effort got started by a willingness to use the same 
documentation "technology" across all TYPO3 community projects.

2) discuss what tools to use for steps that are yet to be taken, like 
completing the rendering chain, job queue management and 
non-documentation pages on the new documentation site. In particular 
where did it make sense to use FLOW3 and where not.

The raw minutes are there:

https://notes.typo3.org/p/DocTeam-FLOW3%20Meeting

Below is a summary:

For point 1, Christian Müller of the FLOW3 team will take contact with 
Fabien Udriot, who has been working on the new, reST-based documentation 
template. This will ensure that we have - in the future - a single 
documentation template for all community projects, and that manuals 
based on it can enter the new rendering workflow without worries. We 
don't expect any bad surprise here as everyone has mostly been following 
common practices.

Point 2 was obviously more wide-ranging, I'll make just a bullet-point 
summary of the discussion:

- job queue: we need a job queue to manage the requests for 
documentation rendering. This can be handled by the FLOW3 job queue 
package, or by some extension of it.
- rendering chain: the scripts used in the rendering chain should in 
whatever (scripting) language is most convenient to use. It doesn't need 
to be FLOW3 all the way. Martin already has quite a few Python scripts, 
since reST is more commonly used in the Python community.
- triggers: documentation rendering must be triggered at some point and 
from a variety of sources. It remains to be seen which is best in each 
situation, but the trigger would call a remote service of the job queue 
handle to register a job.
- database: we want to create DB entries for each rendered manual. This 
will be managed by FLOW3, with a Domain Model to be defined for the 
documentation.
- landing or index pages: we plan to serve the rendered documentation as 
static HTML, but the site will need some dynamic pages, for example for 
lists of manuals and such. This will be handled by FLOW3 with Fluid 
views. Phoenix seems overkill at this point, but could be used later.
- enriching the pages: the static pages will be enriched using AJAX. The 
most desired feature and best candidate is a commenting system. One is 
being developed for FLOW3 and we plan to use it for documentation. It 
could be the basis for a community-wide commenting system.
- embedded documentation: the documentation could also be embedded into 
existing sites. The FLOW3 team has experimented with this for 
flow3.typo3.org. Xavier has also created a TYPO3 plugin for this [1], so 
the possibilities are there, although this is not the top priority.

The FLOW3 team will create a FLOW3 distribution for the documentation 
site. It will include all the necessary packages, in particular DocTools 
which should become the reference package for all things relating to 
documentation.

Besides that we don't have precise tasks yet, but once we have a clear 
vision we will probably call out to developers for help.

Feel free to ask questions (or make corrections if you were in the 
meeting ;-) ).

Cheers

-- 

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

[1] http://forge.typo3.org/projects/extension-restdoc