Moved a chapter from Sphinx to plone.org developer-manual: experiences and feedback

Hi,

To see how well the new documentation area works I just moved a
chapter from my own doc effort to the new documentation area:
http://plone.org/documentation/manual/developer-manual/internationalization-i18n-and-localization-l10n/
to http://plone.org/documentation/manual/developer-manual/internationalization-i18n-and-localization-l10n/

I don't want to open any old wound here and I really don't care how or
where the documentation is made as long as it exists. However, I
wanted to have a rationale experiement to see should I stop writing
docs in Sphinx and write them directly in plone.org kb section when
collective submissions become available.

- It was really inefficient to work with a little web page edit box -
It took almost two hours to put three Sphinx text files to plone.org
by hand. I tried both Kupu and reST editing.

- A code example longer than five lines was very difficult edit and
manage. Like one on this page
http://plone.org/documentation/manual/developer-manual/internationalization-i18n-and-localization-l10n/translating-text-in-code/i18ndude
I wouldn't even think about writing one there...

- Paragraph reordering, copying-and-pasting from page to another and
such basic operations took a minute instead of seconds

- Should there be a review state? There were only draft and published
- I decided to publish it once

- I got a headache

I sincerely belive that there is a reason why Sphinx was created and
why it excels in developer documentation. By weighting this against
"pressing edit button is so simple" argument and "there should be only
one edit chain" argument, I still believe Sphinx wins in a long run
because writing developer documentation is so much more efficient with
Sphinx and file system based tools. It is true that there is a
learning curve. But the curve is not bad (every Python developer must
face it in some point) and contributors little time will pay back
later when they can write and manage documents faster and easier.

So,

- If you are doing documents which are just one page and have no or
little code you can use plone.org as is

- ...else you'll get the job done faster,  more future-proof and
better looking way if you use Sphinx or similar toolchain

-Mikko

------------------------------------------------------------------------------
Return on Information:
Google Enterprise Search pays you back
Get the facts.
http://p.sf.net/sfu/google-dev2dev