Re: Let's turn off api.plone.org.

Dylan Jay wrote:


> I think the closest is in Mikko/collective new developer documentation
> even though it's not published on plone.org yet.

It could have been, but I regret the decision to not base it on Sphinx.
Nearly all python projects use Sphinx nowadays for *developer*
documentation. 

Even Buildout, Zope2, Repoze and other plone-related technologies opt for
Sphinx.

Rok has created very nice Shpinx-plugins 
http://sharbas.blogspot.com/2008/11/one-week-of-riding-sphinx.html
http://plone.org/support/forums/core#nabble-td1488503


IMHO api.plone.org should look like this:
http://docs.garbas.si/plone-latest/

-1 on disabling api.plone.org without a better alternative
Disabling public API-information, when the only alternative given is a local
grep??

We should find a way to lower the access to the rst-based docs inside each
plone-package, and IMHO Sphinx is the solution for that.


> My feeling is that anything is better than outdated 
> and useless docs at this point

If the versions are clearly mentioned, which is the case here, 
then I don't consider it outdated.
It's not updated, and incomplete, but not outdated.
the docs of plone 2.5.5 or 3.0 don't evolve anymore, but they are not
outdated for plone-sites that still run those versions.

It is certainly wrong to assume all plone-website run on the latest released
version. and therefore only docs of that version should publicized.
If api.plone.org was complete for all recent plone-releases, would we have
this discussion?

I have used api.plone.org occasionally in the past,
and Plone definitely needs autogenerated code. Grep is no substitute.
Grep is a poor man's documentation tool.

Let this this situation:
some newbie developer asks by mail a question
about ATNewsitem-schema and how it relates to ATDocument and baseContent

I sent an url like this:
http://api.plone.org/Plone/3.0/public/frames/products/ATContentTypes/products.ATContentTypes.content.newsitem.ATNewsItem-class.html

Now switch off api.plone.org, and send him a grep-command instead? (with
instruction how to install grep on windows probably)


api.plone.org was a very good idea.  (ok, maybe API is not the correct word)
the docs on plone.org is not subsitute for autogenerated documentation


> but otherwise not very useful and more importantly confusing
> to new people (i.e. the "OMG! Plone is a monster!" reaction.)

So ...  let's obfuscate developer information even further?

question: Do C#/.NET developers need to grep in Microsoft's code to search
how they should program their application?


-- 
Greets,
WouterVH


------------------------------------------------------------------------------
Let Crystal Reports handle the reporting - Free Crystal Reports 2008 30-Day 
trial. Simplify your report design, integration and deployment - and focus on 
what you do best, core application coding. Discover what's new with 
Crystal Reports now.  http://p.sf.net/sfu/bobj-july