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

On 13/12/09 7:00, Mikko Ohtamaa wrote:

> 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

-- 
Author of `Professional Plone Development`, a book for developers who
want to work with Plone. See http://martinaspeli.net/plone-book


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