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

[Mikko Ohtamaa]

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

[Dylan Jay]

Later today I will have a go at adjusting funnelweb to automatically
publish existing HTML such as sphinx into a remote plone site. That
should save some pain. Then if we want we can keep some of the manual
in sphinx abd republish regularly. In fact I think I can get it to
follow redirects so that if we move parts out of one manual to another
they could still get updated from sphinx. That would give us the
option of having a manual with mixed sources if that was prefered.

Dylan Jay
Technical solution manager
PretaWeb 99552830

On 13/12/2009, at 10:00 AM, Mikko Ohtamaa <mikko

Post by Mikko Ohtamaa
Hi,
To see how well the new documentation area works I just moved a
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
---
---
---
---------------------------------------------------------------------
Google Enterprise Search pays you back
Get the facts.
http://p.sf.net/sfu/google-dev2dev
_______________________________________________
Plone-docs mailing list
https://lists.sourceforge.net/lists/listinfo/plone-docs

[Martin Aspeli]

Post by Mikko Ohtamaa
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.

I think we agree, though I just wanted to share my experiences.

I wrote the Dexterity developer manual entirely in plone.org. I
developed the code samples on the file system and copied and pasted
them, obviously, but everything else was done straight into plone.org.
This is arguably one of the most comprehensive manuals we have
(especially taken together with the behaviour and five.grok manuals),
and runs to well over 100 pages if printed.

I also use Sphinx in anger at work.

Personally, I prefer working with Plone. I find the WYSIWYG experience
way more rewarding than reST. I can't say I really understand why you
found it so hard. Re-ordering paragraphs taking minutes? Writing more
than five lines of code is difficult? Why is it more difficult than
writing anything else?

Maybe you had different problems. And equally, I don't hugely care. But
if we *do* go with reST, I'd like to have someone sign up as the reST
fixer-upper for when people like me get too frustrated with the markup
and the pages end up looking wrong or giving errors. The workflow of
editing reST, generating the sources and checking in a browser is
inefficient for me, at least.

I do think Sphinx is great and has an important place in Python world.
However, I think that place is more as package docs (PyPI front page on
steroids, packages.python.org) than as project docs.

IMHO. :)

Martin

[Mikko Ohtamaa]

Post by Martin Aspeli
Personally, I prefer working with Plone. I find the WYSIWYG experience
way more rewarding than reST. I can't say I really understand why you
found it so hard. Re-ordering paragraphs taking minutes? Writing more
than five lines of code is difficult? Why is it more difficult than
writing anything else?

Few rationales:

- Code examples: Managing tab and whitespace is difficult in WYSIWYG
editors. You basically need to use external editor to create the
snippet and then copy-paste it into Plone. Because you know writing
code example is so difficult to have you tend to avoid doing them.

- You have wrapping problems with long code lines (not really long,
like 60 characters)... I think it is always autowrap

- To move text from one page to another is not as easy when you have
pages open in text/editor IDE... document tree navigationing is slow.
Copy-pasting Plone object is easy, but it takes more time. You could
have plenty of pages open in a web browser once, but the workflow does
not encourage it (the edit view is closed after save).

- No paste-as-a-plain text

- WYSIWYG editors tend to have shortcut key problems - some
compromises have been made which keys are trapped by the browser and
which keys are standard in word processing

- Less reliable, no autosave. When you press save there is a slight
change everything is lost. Even if it happens only once and you do not
lose much text you lose all your motivation. Even though plone.org
might not go down, you might hit some keyboard combination which
triggers a browser home page or something, navigates away from the
page. Modern browsers tend to preverse the edited text, but it is just
not working always.

Post by Martin Aspeli
Maybe you had different problems. And equally, I don't hugely care. But
if we *do* go with reST, I'd like to have someone sign up as the reST
fixer-upper for when people like me get too frustrated with the markup
and the pages end up looking wrong or giving errors. The workflow of
editing reST, generating the sources and checking in a browser is
inefficient for me, at least.

I think I have found a compromise solution here :)
Sphinx-to-Plone-SVN-workflow would be nice, but it is pain-in-the-ass
to create (complex code to do a simple thing). I still like to solve
some of the problems mentioned above and I think I have found an entry
level solution for myself

- Alternative "Visual editor" for users who find WYSIWYG editors not
comfortable for developer documentation writing, Bespin:
https://bespin.mozilla.com/ I just checked Bespin "embedded bundle".
It is basically textbox replacement which resembles a code editor. The
tab key works. There are line numbers. Etc. I recommedn you to
download the bundle - it comes with a sample static HTML page example
which shows how the thing works in five seconds. Bespin is still beta,
but I expect it mature quite fast as Mozilla is backing up it.

- Have a Javascript to do regular autosave to local disk using offline
storage http://dev.w3.org/html5/webstorage/ - when we store it locally
we do not need to worry about storing temporary copies in Plone
database or anything along the lines.

- Sphinx converters on the top of normal reST - use all Sphinx reST
directives which all possibly on a single page (means no automatical
cross reference). These include code colorizers, warnings, notes, etc.
This can be done on background on the server using AJAX. . 2 hours of
work.

- reST floating reference card (pop up) - no need to hunt down the
syntax if you are new to reST.

I think I will cook this up - just to satisfy my own need of writing docs.

-Mikko

Ps. I used to write docs at plone.org using Kupu, then I switched to
reST on plone.org and then I started using Sphinx.... though I am
WYSIWYG and mouse users to the bones, after crossing the learning
curve I have found that I am not yet going back to WYSIWYG for
developer docs

[Mikko Ohtamaa]

Forgot one

- WYSIWYG editors do not have reliable undo-redo (when you copy-cut-paste text)

[Martin Aspeli]

Post by Mikko Ohtamaa
Forgot one
- WYSIWYG editors do not have reliable undo-redo (when you copy-cut-paste text)

Can we get the latest release of Products.TinyMCE on plone.org? This
should would probably fix the bulk of your problems, and would be a good
idea anyway.

Martin

[Israel Saeta Pérez]

Post by Mikko Ohtamaa
- Code examples: Managing tab and whitespace is difficult in WYSIWYG
editors. You basically need to use external editor to create the
snippet and then copy-paste it into Plone. Because you know writing
code example is so difficult to have you tend to avoid doing them.
...

Looks like this sphinx-or-plone discussion will never end. :P

I know Mikko doesn't want to work on anything which is not open for
everybody and the current developer-manual in the Plone.org manual section
is not going to be so open, so I propose:

1) Keep the manual section in Plone with TTW editing. We can add TinyMCE,
regular autosave, bespin or whatever we want to ease the editing work. The
Knowledgebase can also benefit from all this stuff.

2) Find a way to publish the collective.developermanual in Sphinx as part of
the Knowledgebase at Plone.org. Dylan is already working on this, right?
Everybody with collective access would be able to edit it, so it would be
quite open. Moreover, the documentation is already in the package so we
wouldn't have to move anything.

Thoughts?

-- israel

-----
Israel Saeta Pérez