[TYPO3-doc] A vision for the TYPO3 documentation

[Francois Suter]

Hi all,

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 typo3_tut 
manual, but this guide should rather be a reference for Editors, listing 
the usual tasks and how to ge 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?

Cheers

-- 

Francois Suter
Cobweb Development Sarl - http://www.cobweb.ch