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

[Mikko O. <mik...@re...>]

>
> 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.

>
> 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