[TYPO3-doc] A vision for the TYPO3 documentation

[bernd wilke]

Am Sun, 28 Feb 2010 18:18:36 +0100 schrieb 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.

thanks for your work. This is work I miss a lot.
 
> 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.

I agree.
 
> 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. 

What about another category like: (released ..., reviewed ..., 
unreviewed ... by association) for all these manuals.

> - 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.

I miss a mandatory information: the TYPO3 version a manual belongs to.
as this might give also hints about the usability of a manual.
With this information everybody can see the usage of "Modern Template 
Building" and "Futuristic Template Building".
 
> 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?

I'm dreaming of an online TSRef with these enhancments:
- a page for every value, 
- whith a clear information about the T3-version it was included and
(end of official documentation part)
- where everyone can add his comments and examples

someone might recognize it: it is like the php-documentation on php.net

bernd
-- 
http://www.pi-phi.de/cheatsheet.html