Re: Fwd: Help document Plone's API

Mikko Ohtamaa wrote:

> I think we can still package "Plone API developer manual" as Sphinx
> friendly as possible. I guess Python itself uses bunch of text files
> to describe its API - now Python 2.6 uses Sphinx at
> http://docs.python.org/ too
> 
> I once came across this useful reST plug in:
> 
> http://pypi.python.org/pypi/ulif.rest/
> 
> It adds bag of reST gimmics, including Python highlighting. I
> sincerely recommend we use something similar for API manual. We could
> even add some Plone specific tags.

I sincerely hate reST. :)

Half the time I upload something to PyPI, the pages get totally screwed 
up. It's about as people-unfriendly as we get in this community. :)

I don't hugely care about technology, but I absolutely, positively veto 
any attempt to drag this effort down the path of being the guinea pig 
for finding and evaluating and building a bunch of technology that's 
different to what we currently have (if it ain't broken, don't fix it).

All I want is a structured set of web pages on plone.org/documentation 
that people can easily find and search.

So far, the best way we have to do that is to build a reference manual. 
Anything else would be disjointed (not searchable through 
plone.org/documentation, for example) and obscure (the publishing 
process is different to any other documentation we have, potentially 
controlled by hacked together scripts and hosted on separate servers).

If someone wants to set out a case for building a competing structure to 
the PloneHelpCenter, then go right ahead. But don't use this initiative 
to do so.

Martin

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


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