What's cooking with the Core Documentation?

By: Francois Suter

A lot has happened with the Core Documentation recently. Let's take a look at both the recent history and the near future.

My original goal was to have an up to date documentation available at the same time TYPO3 4.3 was released. That proved too optimistic as I spent quite a lot of time on the Scheduler. Still the TSref and the TSconfig could be released quite quickly after the 4.3 launch.

Most importantly these two manuals were not just updated. They were really refreshed. Some parts were optimized, many code examples were reviewed (and some updated) and - most importantly - all screenshots were updated. Big thanks go to Martin Holtz, Martin Kuster and Susanne Moog who did all these screenshots, sometimes with great difficulty because some concepts had changed so much since the original ones. Still I had to redo some of them, because of skinning changes that happened shortly before the release of TYPO3 4.3 (the early results from the T3UXW09 sessions). I also tried to address as many bug reports as possible.

This work is currently ongoing for the Core APIs. As you know this is the most massive Core manual and refreshing it is a lot of work. One big issue I stumbled upon is that there are lots of code examples, for example in the chapter about the TCA. To each of these examples correspond one or more screenshots. So in order to refresh a screenshot, you have to repeat those TCA modifications first. Sometimes it requires writing some user functions, whose original code may not work anymore.

After pondering this problem for a while, I came up with the following idea: I created an extension called "examples" into which I started storing all this stuff. This makes it far easier to repeat such changes: install the extension and you're done. I think this extension will also be useful to TYPO3 administrators, especially beginners, who will be able to download it and look at or copy the code examples.

I am pretty happy about this and am looking forward to releasing that extension. My only regret is that I had this idea only rather late in my work on Core APIs, so only a few code examples are in the extension for now.

Another big change happened recently: the Core Documentation SVN repository was migrated. Until now it had been part of the TYPO3 v4 repository, which was not optimal, because it meant that you had to be a member of the Core Team to work on the Core Documentation. While this makes some sense, it is also too restrictive. So I had been wanting to improve the situation for a long time, but postponed it regularly because it seemed rather daunting.

I finally started discussing this with Sebastian Kurfürst, the guardian of Forge. He brought Andreas Wolf into the discussion, since he is our local SVN guru. Andreas' skills with SVN shone again. He managed not only to move the Documentation repository out of the source code repository without losing the SVN history, but he even managed to turn the repository inside out like a sock. Indeed the Documentation part of the old repository had tags, branches and trunk on the top level, with subfolders for each manual. In my dreams I imagined that each manual would have its main folder and each would have branches, tags and trunk below that. Andreas made it real.

After that Sebastian could create the project structure on Forge. There's now a "Core Documentation" project and one subproject per manual. This means that rights can be managed on the general documentation level, but also individually for each manual. There are also individual bug trackers, which will make it easier to report and track issues.

The next step for me is to finish work on the Core APIs manual. It's not as critical as the TSref or TSconfig, but it's still one of the most important TYPO3 manual and thus eagerly awaited by the community.

After that I'll move on to the "TypoScript Syntax and In-Depth Study" (doc_core_ts), which also needs a good scrubbing. It will be an opportunity to make the "TypoScript Templates" (doc_core_tstemplate) manual obsolete, as most of the stuff it contains is already repeated elsewhere. Some other very old manuals will also be officially marked as obsolete. Hopefully to be replaced by newer ones, but this is another story...