Fwd: Fwd: Help document Plone's API

First to make clear: I am not arguing here to enforce Sphinx or
anything on the documentation. I just to want to present a different
point of view.

> This misses the point. "Pythonic" is a word we use to talk about coding
> conventions. Applying it to documentation is silly.

Python is using Sphinx for developer documentation: http://docs.python.org/

repoze.bfg is using Sphinx for developer documentation:
http://docs.repoze.org/bfg/#narrative-documentation

z3c.form is using Sphinx for develoepr documentation:
http://www.carduner.net/docs/z3c.form/

Sphinx homepage quote: "“Cheers for a great tool that actually makes
programmers want  to write documentation!”

etc. Sphinx is becoming quite popular among Python developers.

> We have a proven, feature rich content managed solution on plone.org
> that has existed much longer than Sphinx has. It has a review cycle. It
> is accessible to people like JoAnna and Veda that I'm sure will not be
> happy to manage our documentation via an svn client and an obscure plain
> text markup.

Developer manual writers are Python developers.  Developer manual
readers are Python developers. They are quite familiar with tools like
SVN and Sphinx. The problem is the integration part.

"Developers hate to write documentation in Kupu":
http://n2.nabble.com/Re%3A-If-core-code-is-undocumented-it%27s-broken-%28Was%3A-where-should-developer-documentation-go-%29-tp1511898p1565179.html

> I'm not interested in a debate to displace that. I'm even less
> interested in fracturing our documentation into multiple sources that
> can't be easily cross-referenced, searched or integrated in terms of
> navigation and structure.

True. It would be very unwise to have different doc sources. PHC is
currently very well polished for its task, but please remember there
is a world out there and if we keep in sync with the world it will
contribute to the long term sustainability of the community. Being
eccentric has done bad for many good projects out there (Zope).

We have the best open source content management system. In long term
we can probably figure out, and we need to figure out, how to use
external content sources since that's the direction the world is
heading. External searches are just the beginning.

I am thinking about having something like Plone edit view for files
hosted on SVN repository. In Plone you could edit them using Bespin,
view them as HTML rendered docs. But besides this you could use any
tools of your choice for editing (Eclipse/Vim/Emacs) since they are
just normal files.

> The document I'm talking about here will contain a lot of very small
> pages, each with maybe 2-10 lines of code pasted in. I'm not having a
> very hard time doing that with kupu at the moment for the Dexterity
> manual, so I'm sure we'll manage for this. :)

This is totally correct. The result (content) is now more important
than how it is done and I am pretty sure volunteers are happy to use
Plone :)

As soon as you get up some kind of set up where I can add new pages
(write access for everyone?) I am willing to start writing! :)

Thanks
-Mikko

------------------------------------------------------------------------------
Register Now for Creativity and Technology (CaT), June 3rd, NYC. CaT 
is a gathering of tech-side developers & brand creativity professionals. Meet
the minds behind Google Creative Lab, Visual Complexity, Processing, & 
iPhoneDevCamp as they present alongside digital heavyweights like Barbarian 
Group, R/GA, & Big Spaceship. http://p.sf.net/sfu/creativitycat-com