Documentation

Added by Michael Stucki about 6 years ago

Documentation - Francois Suter

Since the migration to reStructured Text started a lot has happened on and around the new documentation server (docs.typo3.org). Various people worked on different topics (conversion of OpenOffice manuals, rendering to HTML, rendering to PDF, etc.). Although the result works fine, this has led to a lack of overview, a lack of synchronisation between the various services and insufficient documentation about how to run docs.typo3.org. All this must be improved in order for docs.typo3.org to be future-proof.

This project aims at:

  • making an inventory of all tools and bits of code, ensuring that each one is useful (or not) and properly stored in some versioning tool.
  • completing the documentation about all tools used on docs.typo3.org, their installation, setup, use, etc.
  • providing a solid Flow-based framework for driving the rendering, including an API for requesting rendering or querying the documentation database.
  • completing the integration with typo3.org and the TER.
  • enabling JSON rendering and improving PDF rendering.

Strict project management will be enforced to avoid the organic evolution we experienced during the early stages of the reStructured Text migration.

The plan is to kick off the project with a code sprint, to get the team on a single track.

Milestones

Milestone 1 is essentially the above-mentioned code sprint with somme follow-up work. It is all about taking stock of the current situation and setting the goals for the rest of the work.

Milestone 2 is about the "interactive" part of the Flow application: the first goal is to finalise the part about receiving rendering requests, logging them and sending feedback about the process' results. The second goal is to develop a (limited) REST interface to query the documentation database so that any other service (e.g. the TER) can request lists of existing manuals, versions, languages, etc.

Milestone 3 is about rendering of reStructured Text to other formats. The PDF rendering can still be improved, in particular with regards to table structures. JSON rendering should also be available, but is currently blocked by special structures used in the TYPO3 documentation. Milestone 3 can happen in parallel with other milestones.

Milestone 4 is about using the API provided in Milestone 2. The first goal is to enable full interaction with the TER. The TER should be able to trigger a rendering request on docs.typo3.org when an extension is uploaded to it. It should also be able to query docs.typo3.org to assess whether a given manual is available or not. The second goal is to improve the construction of the various landings pages on docs.typo3.org, many of which are currently hard-coded.

Milestone 5 is all about documentation. It can start after Milestone 1 for the parts that will not change, but will obviously be ongoing during the whole project.

Milestone 6 is apart and consists of project management. The whole project is pretty complicated and relies and many different components. Managing such a project is no simple task and should be done in a professional way. It thus makes sense to allocated budget to the task (calculated at around 30% of the rest of the working time, which is a usual amount).