[TYPO3-doc] A vision for the TYPO3 documentation

[Daniel Bruessler]

Hello all,

yes, that sounds very good, so it's easier for other to find what they need.

I got your point with the difference between tutorial and guide. It's a
good idea, but we must be very clear with it, so people can get the
point easily.

How can the readers differentiate easily between the types of the documents?
- Core => better "Core"/ "CoreReferences"/ "compressed" or "Technical"?
- Tutorials (they tell a story with pictures about a topic)
- Guides (they don't have a story, they're an all-embracing collection)

=>

So what's about this:
1. We could look for proper colors. A distinct color for every type -
e.g. blue for the "technical" core-manuals, green for the tutorials, red
for the guides.
2. We should have a short introducing sentence in a turorial or guide so
that people know if they have a guide or a tutorial in hands.
3. Why not asking a designer to create three logos? So it's easy to
differ the manuals on typo3.org, in the wiki, on the printed paper.
4. We need a clear naming. Good prefixes are important for the search of
manuals. For example it's easy to download core-manuals via the EM: the
prefix is "doc_core_"
5. We should have easy steps/ iterations (not a big whole thing what
needs 100 years and 1 million people)

I'm also happy for a discussion about this :-) We shouldn't get in
details yet, first we need to find a good way to go straight forward!

Cheers!
Daniel

== DocTeam ==
Want to help? Just see what topics you're interested in and join us!
http://typo3.org/teams/documentation-team/
http://forge.typo3.org/projects/show/team-docteam

:: Daniel Bruessler - Emilienstr. 10 - 90489 Nuernberg


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