[Typo3-doc] Waht we can do now. was: G'day!

[Charlie Dale]

Robert, I love you. I was thinking we had some big fight ahead of us,
waiting for a word from on high to actually enable us to do work (e.g.,
knowing that changes to typo3.org content would be accepted). This seems to
have been Peter's experience anyway. But you've replied and are all positive
and saying we can get access etc! Hoorah!

OK, I've calmed down now.

Actually, I was so excited by your welcoming new "Start Here" content, that
I attempted to write it tonight.

Unfortunately I didn't get as far as I hoped. Some things about the TYPO3
docs give me the creeps!

For example I worked out that the best installation guide for Unix is in the
INSTALL.txt included with the site package, while the best installation
guide for Windows is probably rather part 1.2 of the Getting Started doc.
Yet there are no less than three documents listed in the matrix that cover
installation on Windows.

Also the system requirements page is actually quite hard to find. No way to
find it through the Documentation section of the site as far as I could
tell. Even a quick search in the left bar didn't work (although I'm sure it
was there in the list somehow, I just couldn't be bothered reading through
10 pages of search results). Of course, eventually I found it linked from
the Download page.

Anyway, enough complaining for tonight! I actually did get some useful
writing down. If you have a moment please have a look at the two possible
approaches to the Start Here page that I've started. The first approach I
tried was a guidebook style. The second is question-based. I actually had a
go at the question-based approach because I had real difficulty writing the
guide approach.

I've realised why no one has done a good Start Here page as yet - because
it's a difficult task! Mainly because the overall doc structure isn't great.
The docs often overlap, and its hard to tell which is more relevant today. I
need to do a lot more poring through the docs before I can provide a useful
Start Here page.

Anyway, below are some attempts.

Cheers,
Charlie

***

POSSIBLE APPROACH, GUIDEBOOK LIKE

Welcome to TYPO3

A website, like life in general, is a complex thing.

TYPO3 recognises this complexity. Like all CMSes, it seeks to mitigate this
complexity. But, perhaps uniquely among the free CMSes, TYPO3 doesn't
actually make website creation and management _simple_. This is a good
thing. Because TYPO3 lets you do what you want to do with your website.
Crazy, unique, beautiful, ugly, managed by thousands, managed by one,
whatever. And this is often going to require heavy customisations, that
perhaps even reach into the heart of the CMS and do some bloody surgery.

But why is it important to realise that TYPO3 is a complex thing? Because
the TYPO3 documentation reflects this complexity. Sure, there are many ways
the docs could be improved, simplified, extended, whatever. But I suspect
that they will always be complex, and perhaps even frustratingly complex.

If you want a hope of surviving the TYPO3 documentation jungle, take a few
moments to read this guide.

Installation

Installing TYPO3 consists of a number of steps. You may be able to skip some
depending on the set up of your server. Essentially you need to (1) set up a
web server with PHP and a database server, with optional software, (2)
download and unpack TYPO3, setting permissions and directories correctly,
(3) use the install tool to get TYPO3 running.

...

1. Set up a web server (probably Apache or IIS), running PHP. Unix - read
INSTALL.txt which is contained in the .tar.gz .
2. Install any additional software that TYPO3 will use: perhaps ImageMagick,
zlib or mod_rewrite.
3. Download and unpack the TYPO3 source and a starter website package.
4. Use the install tool to get TYPO3 running.

For specifics of what is required to run TYPO3, check <a
href="http://typo3.org/download/system-requirements/">requirements for
running TYPO3</a>

There are docs to help you with all of these steps. 

***

POSSIBLE APPROACH, QUESTION BASED

How do I install TYPO3?

On Windows, read the <a
href="http://typo3.org/documentation/document-library/doc_tut_quickstart/Ins
tallation-15/">Installation section of "Getting Started"</a>.

On Unix, <a href="http://typo3.org/download">download</a> the QuickStart and
TYPO3 source packages. Inside the quickstart-3.x.x.tar.gz you'll find an
excellent little install guide in INSTALL.txt. This steps you concisely
through the journey of setting up TYPO3. Make sure you do what it says!

I've got a working TYPO3 installation, now what do I do?

Hopefully this is an obvious answer: work through the <a
href="http://typo3.org/documentation/document-library/doc_tut_quickstart/">G
etting Started</a> tutorial, starting at <a
href="http://typo3.org/documentation/document-library/doc_tut_quickstart/Bac
kend_and_frontend/">General principles</a>. Here Kasper takes you through
all the essentials of TYPO3. As a bonus it includes some wacky grammar and
lots of witty comments - it's fun!

What is this TypoScript thing??

OK, don't panic. TypoScript is not as scary as it sounds. In fact, I'm going
to explain it to you right here, otherwise you may be confused while reading
all the docs about it. [Link to various TypoScript docs. Need to work out
which actually is a good starter.]