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

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 
+plone-75aZqqp77KCaMPzRcYMCawC/[email protected]> wrote:

> 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
> _______________________________________________
> Plone-docs mailing list
> [email protected]
> https://lists.sourceforge.net/lists/listinfo/plone-docs

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