[TYPO3-english] Bye-bye OpenOffice, welcome ReST

[Xavier Perseguers]

Hi Dmitry,

> Xavier Perseguers wrote:
>> No, reStructuredText is text-based and there are currently no good
>> graphical editor for this (check the wiki [1] if you want to use one
>> anyway).
>>
>> You should think of it as when writing HTML in the old days. Then we got
>> HTML editors and after a while, most of us went back to good old notepad
>> or other pure text editor because it just was more convenient, but this
>> time with syntax highlighting and autocompletion, because, well, it
>> helps a lot!:)
> 
> Which means, I have to put additional efforts to docs beyond
> programming... Given the fact that many extension authors write docs
> very fomally (meaning "very brief, just to show that there is a doc"), I
> expect that there will be even less docs now.

If they want to write a very brief doc then they could have a single
README.rst at the root of their extension, just as they are encouraged
to do when (git) hosting their project on Github (it's suggested in
Markdown, not ReST but both are supported and both are quite similar).

> What was the reason behind the change? Was it a hope that extension
> authors will rush to learn a new syntax and be happy to write docs using
> tags instead of a word processor? :)

There is no tag, there is markup just as in wikis. The rationale has
been explained numerous time and I can direct you to a few news:

- Documentation has converged:
http://typo3.org/news/article/documentation-has-converged/
- The documentation team in early 2013:
http://typo3.org/news/article/the-documentation-team-in-early-2013/

To make a long story short, if as extension author you want to stick
with OpenOffice, you may do so. TYPO3 community has shown over the years
what backward compatibility means and that we all care about it. It's fine.

Personally, I see the move to ReST as good for many reasons:

- It's text and image are separate, I can finally version my doc just as
my code and I may easily change/update my pictures and diagrams

- When someone creates a patch for one of my extensions, the
documentation can be updated as well, in a clear manner. When I do that
for Core, it's the same, when I spot a typo in one of the official
documents, it's again the same so I know how it works and I'm very efficient

- I finally can consult my documentation on the go, without having to
install OpenOffice which even it is open-source, I could never managed
to "like" and I used it only for TYPO3 manuals, every time hoping it
wouldn't put my all documentation apart and screw everything up. It is
now text-based, so I may read it like that as a last resort, and
otherwise I can read it as HTML with a beautiful template (something we
never had, even with automatic conversion from OpenOffice which never
was that good) and if I want to print it (who knows?) I may get a very
good looking PDF which is not a dumb print of a HTML, it's a dream!

- Oh, and did I mention that I may include my documentation as part of
my website? Very cool for agencies who can prepare in-house
documentation, show it in Backend for their users, print it for teaching
sessions and publish it as real TYPO3 content to their website for
optimal crawler indexing, all from a single central place. Yes, I
already explained that numerous time, sorry for repeating :)

- Documentation is very important, at least as much as code and I want
to use the best tools around for it. It is not a damn work that must be
done bad and quickly to make someone happy, it is something I can trust
to be as much up-to-date as it is possible and help users and admins to
make the most out of a piece of software.

- We have the TYPO3 framework and the TER, helping code to be shared and
reused and this is an integral part of the ecosystem. Whether you use
pibase or Extbase or even your own framework, you use the TYPO3 API and
you can easily navigate from your code to the Core and back or to
another extension's code. It is all linked. With docs.typo3.org we now
have the same, a unified platform for documentation. And I may finally
do with my own documentation what has started to happen for official
documentation and what I missed a lot as a beginner, then as active
contributor: *links* to further help.

You would like an example? Take TypoScript objects, say TEXT content object:

http://docs.typo3.org/typo3cms/TyposcriptReference/ContentObjects/Text/Index.html

OK, so I may write

10 = TEXT
10.value = Hello World!

Fine! And oh, I see that I have stdWrap properties. Well, what's that?
Where do I find those stdWrap properties? In the old days (not that far
away), you would have googled for it and found tons of links with
"stdWrap", even if *that* particular document (OOo rendered as HTML) but
chances are high you would have landed to the wrong place, explaining
something about stdWrap but not the actual properties that are
contextually relevant to you at that point of time. Now, you may just
click on "stdWrap" from that part and see what it's all about.

Take another example, IMAGE:

http://docs.typo3.org/typo3cms/TyposcriptReference/ContentObjects/Image/Index.html

Take a property, see some "strange" datatype, another cObject, a "if",
whatever, you have many many links helping you to quickly get what it means.

The bottom line is that nowadays, what we need is relations between
pieces of information. OpenOffice cannot fit the bill. I want to be able
to link to existing resources easily, and it's the case because if I
refer to stdWrap, I just have to write:

:ref:`t3tsref:stdwrap`

in my documentation to get a pretty link "stdWrap" to that section in
the official manual, I don't have to bother if the chapter is moved
around. I can do the same for my own documents, between them, to the
official manuals, my documentation is part of a whole and not alone
anymore. And just for that reStructuredText/Sphinx and its cross-link
facility is worth it!

-- 
Xavier Perseguers
Release Manager TYPO3 4.6

TYPO3 .... inspiring people to share!
Get involved: http://typo3.org