Jaap Van Otterdijk
The Need for Faster Feedback
When the documentation team introduced the new PHP-based rendering for TYPO3 documentation, the new tool brought a massive speed improvement in rendering times, a big advantage over the old tools.
However, even though the new renderer is much faster, the feedback loop for large documentation pages can still take several minutes. For example, rendering the TYPO3 Changelog still takes about 5–7 minutes. This long feedback loop results in a less efficient workflow for both Core developers and the Documentation Team when keeping the changelog up to date. Extension developers face this same challenge when updating their extension documentation.
Announcing Live Documentation Preview
Over the past few months, I’ve been working on a new feature to further improve the workflow for documentation editors. Today, we’re announcing the next step in providing faster feedback: Live Documentation Preview, or simply watch mode.
This feature isn’t just for the Documentation Team; it’s for everyone who contributes to TYPO3 documentation, especially extension developers who create guides and manuals for their projects. Documentation is at the heart of the TYPO3 ecosystem, and this tool makes it easier to refine and improve your documentation as you go.
How It Works: Automatic Re-Rendering and WebSockets
With this new feature, the render-guides tool maintained by the Documentation Team can now detect changes in your documentation as you edit. When a change is detected, the tool automatically re-renders the affected file so you can see your updates instantly in your browser. For extension developers, this means you can quickly preview your documentation as you update it, reducing the friction between development and documentation.
To make it even more convenient, we’ve included a local web server in the tool that supports WebSockets. WebSockets allow the server to push updates to your browser and trigger an automatic reload of the current page. This means that while you keep your editor open, your browser will refresh automatically, showing your changes in real time.
Our tests show that updates are reloaded within seconds, even for large projects like the changelog.
Current Limitations
There are, however, a few current limitations:
- New pages are not detected.
- Removals are not detected.
- A first full run is required before changes can be detected (for example, the changelog still takes about five minutes on first render).
- Menu changes do not always update correctly.
Looking Ahead: Future Improvements
We’ll continue improving the tool to resolve these limitations and add more features that further optimize your workflow. As extension developers, we know your time is precious, and we’re committed to delivering tools that support your ongoing need to write clear, accurate documentation quickly and efficiently.
We hope that with this addition, editing documentation for your extensions or the TYPO3 Core becomes even easier and more enjoyable.
Felicity Brand
Mathias Bolt Lesniak