Help document Plone's API

[Martin Aspeli]

Hi guys,

I'm looking for a volunteer to drive an effort to improve Plone's API
documentation. I posted a message to the product-developers list
earlier, which had modest response. However, I know several people are
very keen to see this happen, including myself, obviously. :)

I don't have the time to write this documentation, but I will do my best
to help, answering questions, finding examples, and reviewing.

This is probably a couple of weeks' worth of volunteer time, and will
require someone with at least some programming experience. On the other
hand, it's probably less work than the AT tutorial and we pulled that
off. ;)

The message I posted earlier is reproduced below. If anyone's
interested, please respond here!

...

We've recently had some discussions about what Plone's "API" looks like.
The challenge, of course, is that so many things are customisable, so
"the API" is really a very loose term, when you can call just about
anything.

That said, I think there are about 50-100 interfaces/tools/functions
that cover 80% of what most of us do day-to-day. If we can capture
those, we can do some useful things like:

   - identify which APIs suck
   - identify which APIs we're missing (i.e. we end up having to poke at
internals when we should have some clearly defined interface)
   - identify where we have duplication and can consolidate APIs
   - document!

As an end goal, I'd like us to extend and refactor the "Manipulating
Plone Objects Programmatically" tutorial[1] into a more hierarchically
structured reference manual that covers the most common tasks. Some
tasks may require references to other tutorials (e.g. the Archetypes
tutorial), but at least it's a starting point and a place to collate
future APIs as well.

The current groupings and lists of APIs can be found here:

    http://www.mindmeister.com/21419197

That mind map is public, though you may need to sign up for an account
(OpenID support makes that pretty quick if you have that already). I can
also give you access to edit the mind map if you want to collaborate:
just drop me an email with your MindMeister user id.

Cheers,
Martin

[1]http://plone.org/documentation/tutorial/manipulating-plone-objects-programmatically

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


------------------------------------------------------------------------------
Crystal Reports - New Free Runtime and 30 Day Trial
Check out the new simplified licensing option that enables
unlimited royalty-free distribution of the report engine
for externally facing server and web deployment.
http://p.sf.net/sfu/businessobjects
_______________________________________________
Plone-docs mailing list
[hidden email]
https://lists.sourceforge.net/lists/listinfo/plone-docs

[Israel Saeta Pérez]

On Wed, May 20, 2009 at 3:20 PM, Martin Aspeli wrote:

> Hi guys,
>
> I'm looking for a volunteer to drive an effort to improve Plone's API
> documentation. I posted a message to the product-developers list
> earlier, which had modest response. However, I know several people are
> very keen to see this happen, including myself, obviously. :)
>
> I don't have the time to write this documentation, but I will do my best
> to help, answering questions, finding examples, and reviewing.
>
> This is probably a couple of weeks' worth of volunteer time, and will
> require someone with at least some programming experience. On the other
> hand, it's probably less work than the AT tutorial and we pulled that
> off. ;)
>
> The message I posted earlier is reproduced below. If anyone's
> interested, please respond here!

I'd love to participate on that but I currently don't have the time
and won't have it until late June due to my exams. :-/

I'm not sure if a big tutorial like the "Managing Plone Objects
Programmatically" is the best approach here. Currently we're trying to
refactorize existing docs into manuals, more or less by topics, and
each of these manuals could include one or more pages describing the
API. For example, the WorkflowTool API could be explained inside the
workflow manual. What do you think about that?

In the future I would like the API documentation to be generated
directly from the doctests and sphinx or similar tools would be very
helpful here.

-- israel
p.s. Martin, we got a portlets manual for developers that needs
review... would you like to take a quick look at it?

------------------------------------------------------------------------------
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 asthey present alongside digital heavyweights like Barbarian
Group, R/GA, & Big Spaceship. http://www.creativitycat.com 
_______________________________________________
Plone-docs mailing list
[hidden email]
https://lists.sourceforge.net/lists/listinfo/plone-docs

[Martin Aspeli]

Israel Saeta Pérez wrote:

> I'd love to participate on that but I currently don't have the time
> and won't have it until late June due to my exams. :-/

I suspect we won't get anything moving until then, so if you do want to
own this, that'd be great. ;)

> I'm not sure if a big tutorial like the "Managing Plone Objects
> Programmatically" is the best approach here. Currently we're trying to
> refactorize existing docs into manuals, more or less by topics, and
> each of these manuals could include one or more pages describing the
> API. For example, the WorkflowTool API could be explained inside the
> workflow manual. What do you think about that?

That doesn't solve the problem.

We indeed should describe relevant practices inside the specific
manuals. And we should indeed have tutorials/manuals that go in depth
into a topic. But that's not what I'm getting at here.

People need a more concise overview to find examples of the most common
code patterns. That "manipulating objects programatically" is, I
suspect, one of the more read tutorials on plone.org. It's not meant to
*explain* every topic. It's just meant to give you a reference for how
to get things done that you can keep in one place and keep referring
back to. The lack of this type of reference is holding us back, and has
been for years.

> In the future I would like the API documentation to be generated
> directly from the doctests and sphinx or similar tools would be very
> helpful here.

That's a different issue again. It'd be great to expose this. However,
there's too many doctests and interfaces and no structure (other than
the arbitrary package structure of the code they're bundled with)
that'll help people find what they need. If you look at that mindmap,
many of the groupings sit across three or four packages.

> -- israel
> p.s. Martin, we got a portlets manual for developers that needs
> review... would you like to take a quick look at it?

Yes - email me. :)

Cheers,
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 asthey present alongside digital heavyweights like Barbarian
Group, R/GA, & Big Spaceship. http://www.creativitycat.com 
_______________________________________________
Plone-docs mailing list
[hidden email]
https://lists.sourceforge.net/lists/listinfo/plone-docs

[Dylan Jay-4]

On 21/05/2009, at 10:59 AM, Martin Aspeli wrote:

> Israel Saeta Pérez wrote:
>
>> I'd love to participate on that but I currently don't have the time
>> and won't have it until late June due to my exams. :-/
>
> I suspect we won't get anything moving until then, so if you do want  
> to
> own this, that'd be great. ;)
>
>> I'm not sure if a big tutorial like the "Managing Plone Objects
>> Programmatically" is the best approach here. Currently we're trying  
>> to
>> refactorize existing docs into manuals, more or less by topics, and
>> each of these manuals could include one or more pages describing the
>> API. For example, the WorkflowTool API could be explained inside the
>> workflow manual. What do you think about that?
>
> That doesn't solve the problem.
>
> We indeed should describe relevant practices inside the specific
> manuals. And we should indeed have tutorials/manuals that go in depth
> into a topic. But that's not what I'm getting at here.
>
> People need a more concise overview to find examples of the most  
> common
> code patterns. That "manipulating objects programatically" is, I
> suspect, one of the more read tutorials on plone.org. It's not meant  
> to
> *explain* every topic. It's just meant to give you a reference for how
> to get things done that you can keep in one place and keep referring
> back to. The lack of this type of reference is holding us back, and  
> has
> been for years.

+10

>> In the future I would like the API documentation to be generated
>> directly from the doctests and sphinx or similar tools would be very
>> helpful here.
>
> That's a different issue again. It'd be great to expose this. However,
> there's too many doctests and interfaces and no structure (other than
> the arbitrary package structure of the code they're bundled with)
> that'll help people find what they need. If you look at that mindmap,
> many of the groupings sit across three or four packages.

Perhaps it's too daunting for one person to take on. I'd love to  
contribute but I'm very overloaded like everyone else I imagine. The  
structure in the mindmap is very good. Perhaps we could divide that up  
among several people and someone else could join them together into a  
single narrative?

>> -- israel
>> p.s. Martin, we got a portlets manual for developers that needs
>> review... would you like to take a quick look at it?
>
> Yes - email me. :)
>
> Cheers,
> 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 asthey present alongside digital heavyweights like  
> Barbarian
> Group, R/GA, & Big Spaceship. http://www.creativitycat.com
> _______________________________________________
> Plone-docs mailing list
> [hidden email]
> https://lists.sourceforge.net/lists/listinfo/plone-docs

------------------------------------------------------------------------------
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 asthey present alongside digital heavyweights like Barbarian
Group, R/GA, & Big Spaceship. http://www.creativitycat.com 
_______________________________________________
Plone-docs mailing list
[hidden email]
https://lists.sourceforge.net/lists/listinfo/plone-docs

[Martin Aspeli]

Dylan Jay wrote:

> Perhaps it's too daunting for one person to take on. I'd love to  
> contribute but I'm very overloaded like everyone else I imagine. The  
> structure in the mindmap is very good. Perhaps we could divide that up  
> among several people and someone else could join them together into a  
> single narrative?

Yeah, I think that makes sense. I'd still like one person to own and
manage the document.

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 asthey present alongside digital heavyweights like Barbarian
Group, R/GA, & Big Spaceship. http://www.creativitycat.com 
_______________________________________________
Plone-docs mailing list
[hidden email]
https://lists.sourceforge.net/lists/listinfo/plone-docs

[Israel Saeta Pérez]

On Thu, May 21, 2009 at 2:59 AM, Martin Aspeli <[hidden email]> wrote:
> Israel Saeta Pérez wrote:
>
>> I'd love to participate on that but I currently don't have the time
>> and won't have it until late June due to my exams. :-/
>
> I suspect we won't get anything moving until then, so if you do want to
> own this, that'd be great. ;)

Cool!

>> In the future I would like the API documentation to be generated
>> directly from the doctests and sphinx or similar tools would be very
>> helpful here.
>
> That's a different issue again. It'd be great to expose this. However,
> there's too many doctests and interfaces and no structure (other than
> the arbitrary package structure of the code they're bundled with)
> that'll help people find what they need. If you look at that mindmap,
> many of the groupings sit across three or four packages.

Ok we can try to identify and document the API using the current
mindmap as basis. I prefer to work rather to argue, since we can
always copy-paste documentation inside a manual, doctests or whatever.
:)

-- israel

------------------------------------------------------------------------------
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 asthey present alongside digital heavyweights like Barbarian
Group, R/GA, & Big Spaceship. http://www.creativitycat.com 
_______________________________________________
Plone-docs mailing list
[hidden email]
https://lists.sourceforge.net/lists/listinfo/plone-docs

[Mikko Ohtamaa]

I volunteer to have

1) HTTP request and HTTP response

2) Workflows

3) Sessions

4) Property sheets (portal_properties)

5) Overriding site views, viewlets and utilities

I don't volunteer to have

1) traversing (after 5 years I don't understand properly...)

2) transactions and Zope persistency (don't understand test layer part
+ some persistency magic)

3) CMFFormController and old Python scripts (ugh)

Some open questions:

1) how do we relate this to the current Archetypes tutorial?

------------------------------------------------------------------------------
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 
_______________________________________________
Plone-docs mailing list
[hidden email]
https://lists.sourceforge.net/lists/listinfo/plone-docs

[Mikko Ohtamaa]

---------- Forwarded message ----------
From: Mikko Ohtamaa <[hidden email]>
Date: 2009/5/26
Subject: Re: [Plone-docs] Help document Plone's API
To: Israel Saeta Pérez <[hidden email]>
Cc: Martin Aspeli <[hidden email]>, [hidden email]


>> That's a different issue again. It'd be great to expose this. However,
>> there's too many doctests and interfaces and no structure (other than
>> the arbitrary package structure of the code they're bundled with)
>> that'll help people find what they need. If you look at that mindmap,
>> many of the groupings sit across three or four packages.

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.

-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 
_______________________________________________
Plone-docs mailing list
[hidden email]
https://lists.sourceforge.net/lists/listinfo/plone-docs

[Dylan Jay-4]

On 22/05/2009, at 9:11 PM, Martin Aspeli wrote:

> Dylan Jay wrote:
>
>> Perhaps it's too daunting for one person to take on. I'd love to
>> contribute but I'm very overloaded like everyone else I imagine. The
>> structure in the mindmap is very good. Perhaps we could divide that  
>> up
>> among several people and someone else could join them together into a
>> single narrative?
>
> Yeah, I think that makes sense. I'd still like one person to own and
> manage the document.

I can have a go and getting people working on it and stitching it  
togeather.




------------------------------------------------------------------------------
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 
_______________________________________________
Plone-docs mailing list
[hidden email]
https://lists.sourceforge.net/lists/listinfo/plone-docs

[Dylan Jay-4]

On 23/05/2009, at 12:37 PM, Israel Saeta Pérez wrote:

> On Thu, May 21, 2009 at 2:59 AM, Martin Aspeli <[hidden email]
> > wrote:
>> Israel Saeta Pérez wrote:
>>
>>> I'd love to participate on that but I currently don't have the time
>>> and won't have it until late June due to my exams. :-/
>>
>> I suspect we won't get anything moving until then, so if you do  
>> want to
>> own this, that'd be great. ;)
>
> Cool!
>
>>> In the future I would like the API documentation to be generated
>>> directly from the doctests and sphinx or similar tools would be very
>>> helpful here.
>>
>> That's a different issue again. It'd be great to expose this.  
>> However,
>> there's too many doctests and interfaces and no structure (other than
>> the arbitrary package structure of the code they're bundled with)
>> that'll help people find what they need. If you look at that mindmap,
>> many of the groupings sit across three or four packages.
>
> Ok we can try to identify and document the API using the current
> mindmap as basis. I prefer to work rather to argue, since we can
> always copy-paste documentation inside a manual, doctests or whatever.
> :)

I think martin is right in that I would think that most of it would be  
written not autogenerated or included. Most existing doctests in plone  
aren't going to be highlevel enough to run smoothly in a "programatic  
plone" manual.  However it would be nice to use doctest format so we  
could regression test the manual. We could then have the option to  
include something if it was appropriate without having to cut and paste.

Then when the manual is done, the final html result, we just cut and  
paste into plone.
.




------------------------------------------------------------------------------
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 
_______________________________________________
Plone-docs mailing list
[hidden email]
https://lists.sourceforge.net/lists/listinfo/plone-docs

[Martin Aspeli]

Mikko Ohtamaa wrote:
> I volunteer to have

Cool!

I still need someone to own the overall document/structure. If that's
Israel, then that's great.

> 1) HTTP request and HTTP response
>
> 2) Workflows
>
> 3) Sessions
>
> 4) Property sheets (portal_properties)
>
> 5) Overriding site views, viewlets and utilities
>
> I don't volunteer to have
>
> 1) traversing (after 5 years I don't understand properly...)
>
> 2) transactions and Zope persistency (don't understand test layer part
> + some persistency magic)
>
> 3) CMFFormController and old Python scripts (ugh)

Let's get the structure in place in a Reference Manual on plone.org with
sections and pages, and then people can just start filling in pages.

> Some open questions:
>
> 1) how do we relate this to the current Archetypes tutorial?

Just link to it where appropriate. Remember, the goal here is not to
teach you everything you need to know about Plone. Rather, we're aiming
to have an easily accessible single place to find the most common/useful
APIs (and, further down the line, a way for us to "bless" those as
official and sanction changes to them over time in a controlled manner).

I suspect there'll be a lot of "For more information and background, see
..." type links.

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 
_______________________________________________
Plone-docs mailing list
[hidden email]
https://lists.sourceforge.net/lists/listinfo/plone-docs

[Martin Aspeli]

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 
_______________________________________________
Plone-docs mailing list
[hidden email]
https://lists.sourceforge.net/lists/listinfo/plone-docs

[Martin Aspeli]

Dylan Jay wrote:

> On 23/05/2009, at 12:37 PM, Israel Saeta Pérez wrote:
>
>> On Thu, May 21, 2009 at 2:59 AM, Martin Aspeli <[hidden email]
>>> wrote:
>>> Israel Saeta Pérez wrote:
>>>
>>>> I'd love to participate on that but I currently don't have the time
>>>> and won't have it until late June due to my exams. :-/
>>> I suspect we won't get anything moving until then, so if you do  
>>> want to
>>> own this, that'd be great. ;)
>> Cool!
>>
>>>> In the future I would like the API documentation to be generated
>>>> directly from the doctests and sphinx or similar tools would be very
>>>> helpful here.
>>> That's a different issue again. It'd be great to expose this.  
>>> However,
>>> there's too many doctests and interfaces and no structure (other than
>>> the arbitrary package structure of the code they're bundled with)
>>> that'll help people find what they need. If you look at that mindmap,
>>> many of the groupings sit across three or four packages.
>> Ok we can try to identify and document the API using the current
>> mindmap as basis. I prefer to work rather to argue, since we can
>> always copy-paste documentation inside a manual, doctests or whatever.
>> :)
>
> I think martin is right in that I would think that most of it would be  
> written not autogenerated or included. Most existing doctests in plone  
> aren't going to be highlevel enough to run smoothly in a "programatic  
> plone" manual.  However it would be nice to use doctest format so we  
> could regression test the manual. We could then have the option to  
> include something if it was appropriate without having to cut and paste.
>
> Then when the manual is done, the final html result, we just cut and  
> paste into plone.

If you want to do that for a section you're writing, feel free, of
course. But the overhead of doing this is more than you may think. You
need a lot of test setup, and it quickly becomes difficult to manage
different sandboxes and test case layers. For some APIs it'll be quite
easy. For others, it'll be pretty awkward, and require trade-offs in
terms of readability to make the tests run.

And then, what do you do once someone goes to edit the copy on
plone.org? It's not exactly good content management. ;-)

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 
_______________________________________________
Plone-docs mailing list
[hidden email]
https://lists.sourceforge.net/lists/listinfo/plone-docs

[claytron]

On May 26, 2009, at 10:17 PM, Martin Aspeli wrote:

> Mikko Ohtamaa wrote:
>
>> <snip>
>>
>> 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 also dislike reST. It's terribly strict and quite hard to use for  
mere mortals.  I spend a lot of time fixing up reST long_descriptions  
on collective packages (that aren't mine) just because I can't stand  
to see the pages broken :D

That being said, it is quite powerful once you are used to it, but I  
still prefer writing docs in markdown or something similar.

claytron
--
S i x  F e e t  U p ,  I n c .  |  http://www.sixfeetup.com
Phone: [phone] x603
[hidden email]
ANNOUNCING the first Plone Immersive Training Experience | Sept.  
10-11-12, 2009
http://www.sixfeetup.com/immerse

------------------------------------------------------------------------------
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 
_______________________________________________
Plone-docs mailing list
[hidden email]
https://lists.sourceforge.net/lists/listinfo/plone-docs

[JoAnna Springsteen]

> I sincerely hate reST. :)

+1 keep it off plone.org.


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

+1 again. Use what we have, especially if you want it to continue to
be supported as things change.


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

Can we hold off on creating the structure until after this weekend?
We're testing the new PHC and this may (or may not) impact how we do
this.
Don't get me wrong, it shouldn't make things difficult. You just might
get some extras if you wait a bit.



J.

------------------------------------------------------------------------------
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 
_______________________________________________
Plone-docs mailing list
[hidden email]
https://lists.sourceforge.net/lists/listinfo/plone-docs

[Mikko Ohtamaa]

> I also dislike reST. It's terribly strict and quite hard to use for
> mere mortals.  I spend a lot of time fixing up reST long_descriptions
> on collective packages (that aren't mine) just because I can't stand
> to see the pages broken :D

Check http://pypi.python.org/pypi/collective.checkdocs/0.1.1 for
checking reST :)

reST is terrible and I hate it too. But for writing code documents
it's the best tool we have and I hate alternatives even more.

But as long as browsers/rich editor/Kupu fail to do <pre> editing in
any sane (messed up formatting, missing new lines, double new lines)
way I don't like tie idea of writing any code documents in browser
WYSIWYG editor.

Also, Sphinx seems to be the upcoming de facto standard to document
Python. I hope we don't have yet another case here of being
unpythonic. Sphinx is also proven technology (python.org). I am not
sure how tighly Sphinx and reST are coupled if something better than
reST comes up.

-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 
_______________________________________________
Plone-docs mailing list
[hidden email]
https://lists.sourceforge.net/lists/listinfo/plone-docs

[Vincent Fretin]

On Wed, May 27, 2009 at 10:32 AM, Mikko Ohtamaa
<[hidden email]> wrote:
>> I also dislike reST. It's terribly strict and quite hard to use for
>> mere mortals.  I spend a lot of time fixing up reST long_descriptions
>> on collective packages (that aren't mine) just because I can't stand
>> to see the pages broken :D
>
> Check http://pypi.python.org/pypi/collective.checkdocs/0.1.1 for
> checking reST :)

Hi,

Tarek Ziade added a check distutils command in collective.dist, an
will be in Python 2.7 I think.
So you can do:
python setup.py check --strict
to check long_description reST.

You can do:
python setup.py --long-description | rst2html.py > /tmp/foo.html
and open /tmp/foo.html in your browser too.

Regards
--
Vincent Fretin

------------------------------------------------------------------------------
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 
_______________________________________________
Plone-docs mailing list
[hidden email]
https://lists.sourceforge.net/lists/listinfo/plone-docs

[Martin Aspeli]

Mikko Ohtamaa wrote:

> Also, Sphinx seems to be the upcoming de facto standard to document
> Python. I hope we don't have yet another case here of being
> unpythonic.

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

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.

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.

Rather than this vaguely posturing that some different technology may be
better for producing the content, we should focus on the important part:
the content itself. For better or worse, PHC is the documentation story
on plone.org, and there is no clear path or consensus for using anything
else. In the worst case, we'll end up with a half-arsed solution that
no-one maintains, no-one knows where to access, and no-one knows how to
integrate into plone.org. In the best case, we spend a ton of effort on
technology that we could spend on content and still be no better off.

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

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 
_______________________________________________
Plone-docs mailing list
[hidden email]
https://lists.sourceforge.net/lists/listinfo/plone-docs

[Mikko Ohtamaa]

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 
_______________________________________________
Plone-docs mailing list
[hidden email]
https://lists.sourceforge.net/lists/listinfo/plone-docs

[claytron]

On May 27, 2009, at 5:03 AM, Vincent Fretin wrote:

> On Wed, May 27, 2009 at 10:32 AM, Mikko Ohtamaa
> <[hidden email]> wrote:
>>> I also dislike reST. It's terribly strict and quite hard to use for
>>> mere mortals.  I spend a lot of time fixing up reST  
>>> long_descriptions
>>> on collective packages (that aren't mine) just because I can't stand
>>> to see the pages broken :D
>>
>> Check http://pypi.python.org/pypi/collective.checkdocs/0.1.1 for
>> checking reST :)
>
> Hi,
>
> Tarek Ziade added a check distutils command in collective.dist, an
> will be in Python 2.7 I think.
> So you can do:
> python setup.py check --strict
> to check long_description reST.
>
> You can do:
> python setup.py --long-description | rst2html.py > /tmp/foo.html
> and open /tmp/foo.html in your browser too.

I use the following command so that you can see where the errors are  
in the compiled long_description, otherwise you have to hunt the error  
down:

python2.4 setup.py --long-description > /tmp/package.rst &&  
rst2html.py /tmp/package.rst /tmp/package.html && mate /tmp/package.rst

And I alias that to 'descrip_check' because I use it so often (I use  
TextMate on the mac, could easily be sent to another program besides  
'mate')

claytron
--
S i x  F e e t  U p ,  I n c .  |  http://www.sixfeetup.com
Phone: [phone] x603
[hidden email]
ANNOUNCING the first Plone Immersive Training Experience | Sept.  
10-11-12, 2009
http://www.sixfeetup.com/immerse

------------------------------------------------------------------------------
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 
_______________________________________________
Plone-docs mailing list
[hidden email]
https://lists.sourceforge.net/lists/listinfo/plone-docs