Re: Fwd: Fwd: Help document Plone's API

On 27/05/2009, at 9:34 PM, Mikko Ohtamaa wrote:

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

Totally agree and would also add that during the last plone conference  
I ran a BOF session on gathering feedback on newbies find hard about  
Plone. One item was that code snippets often didn't work.
If there is a way to keep the documentation maintainable in plone, but  
testable at the same time then it could reduce the maintenance tasks  
of the documentation team. With regard to official API documentation,  
I personally think we should be pushing maintenance of this  
documentation as much towards the developers as possible. If they  
can't explain their changes they shouldn't be making them.

Martin Aspeli said...
>> 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.

but what if we could have multiple sources that can be easily cross- 
referenced, searched or integrated in terms navigation and structure?

As you say now is not the time to implement this, as it needs to well  
thought out, but the really useful part of sphinx is the ability to  
include elements from different sources and compile them into one  
document.
If someone does write a well maintained doctest for part of the plone  
core, and it fit's into the api manual, why rewrite it? If there was a  
feature in kupu where you could "insert>linked content" and we could  
get that content from the current plone code base, would it be such a  
mess? Personally I think that it core coders saw that some of their  
documentation was being exposed in an official manual it would lead  
them to raise their game and create even more useful doctests.

Another example is the experiments Rok Garbas did with sphinx last  
year where he blended written documentation with ATCT schema  
documentation generated from the actual schemas. I'm not saying  
generated documentation is always appropriate, just that  when it is,  
the result is more maintainable.

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

+1 I will look though the mindmap after this weekend and pick some  
topics to contribute. This effort is long overdue and I applaud Martin  
for putting it back on the agenda.



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