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 that developers are a different kinds of documentation  
writers and so a different process might be more suited to them. Also  
during the last plone conference I ran a BOF session on gathering  
feedback on newbies on what they find hard about learning Plone. One  
item was that code snippets often didn't work.
If there is a way to keep the documentation easy to edit, but testable  
at the same time then it could reduce the maintenance tasks of the  
documentation team.
For 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.

http://docs.garbas.si/plone-latest/content-types.html#document

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

------------------------------------------------------------------------------
OpenSolaris 2009.06 is a cutting edge operating system for enterprises 
looking to deploy the next generation of Solaris that includes the latest 
innovations from Sun and the OpenSource community. Download a copy and 
enjoy capabilities such as Networking, Storage and Virtualization. 
Go to: http://p.sf.net/sfu/opensolaris-get

_______________________________________________
Plone-docs mailing list
[email protected]
https://lists.sourceforge.net/lists/listinfo/plone-docs