This page is about the new vision for TYPO3 documentation.
notice - Note
--Daniel Brüßler 21:40, 1 March 2010 (UTC)
New vision - Francois
As you have probably noticed, I have been very active on the TYPO3 Core documentation recently. In addition to that I have also been thinking about the bigger picture of TYPO3 documentation and try to come up with a vision of what it could be ideally.
Quite a few books have been published recently, which is great in terms of documentation and also shows increased awareness about TYPO3 on the market. While seeing more TYPO3 books makes me very happy, I think that an Open Source project should also have quality, free documentation.
The Documentation Team has produced some very good manuals, like TypoScript in 45 minutes. However I feel like these efforts are not visible enough, in particular because it's in the wiki and not referenced on typo3.org. And they don't cover the whole range of needs for beginners, editors, administrators, etc.
So here are my thoughts and ideas, that I submit to you for discussion.
First of all, I would like to categorize the manuals more strictly. I can see three big categories:
- Core manuals: that would be pretty much what is already considered as "Core documentation" today
- Tutorials: step-by-step learning documents. What I would like to do here is to clearly separate "official" tutorials (reviewed and approved by the Doc Team) from other tutorials created by anyone. That may be unpopular with those who wrote tutorials, but should not be taken as such. First of all, there are not many people who write tutorials anyway. And then I hope that such highly-motivated people would agree to join in writing the official tutorials.
- Guides: this is the real missing link IMO. These manuals should be real practical references. Whereas the core documentation is a technical reference, these should be references for daily work, complete with useful tips & tricks.
More concretely here's what I imagine (trying not to go into too much details at this point):
- the core documentation is pretty complete, but some manuals like Core APIs have become bloated and should probably be split. Some information about APIs could probably be moved to some extension developer's guide. Some very old manuals need to be totally revamped or merged into more recent ones and removed.
- for tutorials, we currently have the install and upgrade guide which is actively maintained (although the installation guide is really a guide, and what we rather need as a tutorial is a getting started; the existing one is in dire need of a refresh; this should work together with the new starter packages planned for TYPO3 4.4 (haven't discussed this yet with the team developing the starter package)). There are some dreadfully outdated manuals like Modern Template Building (which is not modern anymore) and Futuristic Template Building (not really futuristic anymore either). These should be replaced by a new templating tutorial, maybe be incorporating the TS in 45 minutes tutorial (ideally this should also play nice with the new starter package). The TypoScript by Example tutorial should also be refreshed.
- guides are where the most work lies. Here's a list of the guides I could envision:
- Administrator's Guide: how to set up a TYPO3 installation beyond making templates and - especially - how to maintain it, what routine tasks should be performed (like lowlevel cleaning), what logs are available and how to monitor your installation, etc.
- Security Guide: security is an important topic, which is why I think it should be separate from the Administrator's Guide, although it is clearly an administrator's task. I think this one is particularly important, not only because of its topic, but also because there are quite a few unofficial security guides out there, which is fine, but also confusing. I have already broached the subject with the Security Team.
- Editors's Guide: there's a neat start for this with the doc tut editors manual, but this guide should rather be a reference for Editors, listing the usual tasks and how to get about them, the different types of content elements and how to use them, workspaces, etc.
- Programming Guide: this would be a starting point for extension developers. It should probably be split in FE and BE programming. I would put an emphasis on BE programming, as FE is better covered by books, blogs and numerous examples.
- Localization Guide: this one exists and contains a lot of useful information. It probably deserves a review as its content can probably be reorganized a bit in retrospect, but there's a very good basis.
That's quite a bit to digest, I hope it will foster a good discussion.
Most importantly I hope it will generate a will to participate, because it all represents a lot of works and the Doc Team and me will never be able to make that all come true just by ourselves. Then again it's just a vision, but wouldn't it be really great if it came true?