Documentation Recap from the TYPO3 Fluid 3.0 Workshop

This article covers the Fluid 3.0 Workshop. Also, upcoming plans for Fluid are detailed.

History and Current State

Fluid is a standalone Template Engine for the web language PHP. It was initially developed within the TYPO3 Flow web framework, and now everyone can use Fluid. It is used by TYPO3 CMS, Flow, and Neos. 

Claus Due is the current Component Merger for Fluid and responsible for the integration with TYPO3 CMS. As such, he is responsible for Fluid’s code, functionality, backward-compatibility, architecture, and future development.

Up until now, there has been little documentation, only available within the Fluid repository on GitHub, without details on using Fluid with TYPO3. So that is what we focused on in the workshop.

Workshop 3.0

Claus Due invited everyone to participate in Fluid 3.0. The upcoming release will include breaking changes and introduces entirely new concepts. These concepts make Fluid even more flexible. One could, for example, adopt Fluid for design approaches like Atomic Design. 

At the workshop four volunteers from the Documentation Team focused on these improvements in Fluid’s documentation. 

How to Document

To get started with documentation, you need to agree on how you’re going to write documentation and make sure all the tools and processes are in place for collaboration. 

We discussed Markdown because it’s a popular method for formatting text. However, the official TYPO3 documentation uses reStructuredText (reST). Markdown is similar to reST, but it has less features, and some inconsistent quirks when it’s rendered in various formats. You can read more about the decision not to use Markdown here: Writing Documentation. 

By sticking with reStructuredText, Fluid’s documentation will follow all the conventions we’re using in TYPO3 documentation, and later, we can integrate the documentation into existing workflows and infrastructure. 

Improve XSD

XSD (XML Schema Definition), is an XML technology used under the hood. XSD powers auto-completion within IDEs and powers the auto-generated ViewHelper Reference, which is already generated for TYPO3 CMS 9.5 and Fluid 2.x. There were some limitations in the current implementation. During the Workshop, we managed to get around these and started to work on implementation.

This especially showed how awesome Workshops and Sprints can be for all participants. We started to work with pair programming and test-driven development. As we already knew the goal, the new XSD format, we were able to start by writing tests beforehand and to adjust code afterward.

Once finished, the XSD will transport even more information, e.g. allowing PHP Types as Arguments for ViewHelper. It will also be possible to provide multiple possible Types per Argument. This will then be reflected in the auto-generated Reference.

Writing Documentation

Without proper documentation, it’s much harder to get started with Fluid. 

Projects might not even consider Fluid as a possible template engine alternative because of the lack of documentation. Therefore we started building the documentation from existing sources. 

We started with a table of contents, adding in existing documentation from GitHub. We also had the information at fluidtypo3.org in mind. 

We also added a list of sections referencing Fluid to docs.typo3.org. As part of the “Plans for future” (see below) the TYPO3 community will manage this documentation on docs.typo3.org

We highly appreciate the work of Usman Ahmad and Itishree Ghunghru on that topic. They kickstarted the first version of the documentation, based upon the existing sources.

We also highly appreciate the work of Tom Warwick. He collected sources mentioning the Fluid template engine in various places. Also thanks for providing native speaker insights.

Plans for the Future

Finish XSD

The implementation of new features needs to be finished. Some more tests and code has to be written. Also, tools working with the XSD, like the fluid-documentation-generator, need adjustments in the end in order to make use of the new information. The tool to generate XSD can be found on GitHub.

Finish First Version of Documentation

There is still a lot of work. All sources have to be merged into the documentation system. This has to contain all information to start with Fluid as a standalone template engine. 

Besides that, all existing sources need adjustments. They should reference the official Fluid documentation and only provide more specific information on top. Current plans are to deprecate fluidtypo3.org in favour of new official documentation on docs.typo3.org.

Say Thanks

Thanks to all the participants. We know some of you had really long journeys. Also big thanks to the host Systime, for the venue. Their breakfast, lunch, drinks, and atmosphere were really great. And of course thanks to Claus Due for inviting, providing self-brewed beer, self-made coffee, and taking documentation seriously.

If you want to help in any of these areas, check out these resources:

• Blog post: Start Improving Docs Now to Grow TYPO3

Get more information at The TYPO3 Documentation Team page.

  
Proofreading and copyediting: Tony Lush