[Typo3] RealURL For Dummies?

[Sandip Bhattacharya]

Floyd Arguello wrote:
> A-san, I agree with you on some points; Typo3 is a great program with
> inconsistent documentation. I don't think it's necessarily an English
> as a Second Language issue; I think the problem stems from the fact
> that programmers aren't technical writers, and have such an advanced
> knowledge of their product that they don't necessarily consider the
> simple stuff. At the same time, who's going to document their product?
> Are you willing? It's a complaint with no easy and apparent solution.
> I think I can write some good tutorials on some of the extensions and
> plugins I've used, but I don't have the time. I'm sure a lot of people
> have that same issue.

You have got the main point here. The authors are not (yet) great
technical writers, and many a times mix up the flow of their
writeups. :-P 

As a long time web developer with lots of technical writing experience,
I have nevertheless always been amazed with the attention paid on the
width of documentation on Typo3. I have yet to see an Opensource
project with so much documentation. 

The documentations matrix is impressive but needs to be further
organized. Typo3 has been for years standardizing on Openoffice
documentation as its core format and its web rendering of this format
is great. Both of these really impressed me when I forst looked at it.

However, there are many drawbacks yet. 

* I am really surprised that *none* of the reference documents have an
index!! How in the world is somebody going to use such references?
* Some parts of the references are not even alphabetically organized!
How can you use these as references?
* The document matrix is needlessly confusing with separate rows being
given for different languages of the same program. Why not have a
single row with language/country codes as links to different versions
of the same document? 
* At a very minimum keep translations together. Take a look at
"Typoscript by example". There is only the french translation under
references, and the english translation under Other Tutorials.
* Make up your mind - either talk how to configure using TS only, or
visually only, or with the *same* mix of both.

I had a horrid time trying to search for info on how to manage backend
users. I discovered that the best info was in the quickstart document! 

Apart from these I agree to the language issues. I dont mean any offence
when I say that I agree that most of the core documentation is written
by somebody for whom english is the second language. English is my
second language too, and I have spent an agonizing one year listening
to senior technical writers teaching me the finer points of the
language. :) I also happen to be married to a technical writer, so you
can imagine. :-P

Believe me, this language issue is a core thing which might reduce
spread of typo3 in the native english speaking community. Having a
software with a learning curve is fine - when one sees what typo3 can
do, one is convinced that spending time learning it is worth it. But if
the documentation is dense, that will really put people off.

Yes, I would love to write (and even rewrite) typo3 documentation. But
for that I have to get the hang of it first. Right now, I am too busy
running between different typoscript manuals to make my site work. :-P

- Sandip



-- 
Sandip Bhattacharya  *    Puroga Technologies   *     sandip at puroga.com
Work: http://www.puroga.com  *   Home/Blog: http://www.sandipb.net/blog

PGP/GPG Signature: 51A4 6C57 4BC6 8C82 6A65 AE78 B1A1 2280 A129 0FF3