[Distutils] Buildout documentation

[Jim Fulton]

On Fri, Mar 26, 2010 at 2:30 AM, Baiju M <mbaiju at zeomega.com> wrote:
> On Wed, Mar 24, 2010 at 10:27 PM, Baiju M <mbaiju at zeomega.com> wrote:
>> On Wed, Mar 24, 2010 at 10:02 PM, Baiju M <mbaiju at zeomega.com> wrote:
>>> Hi All,
>>>        I can see many people working with Buildout in this list.
>>> There are nearly 200 packages in PyPI with "Framework :: Buildout"
>>> category: http://pypi.python.org/pypi?:action=browse&c=512
>>> This is really amazing.  But the documentation for Buildout
>>> is not sufficient.  I and few others created http://www.buildout.org
>>> during PyCON 2009.  It would be great, if the users of
>>> Buildout coming forward to maintain that documentation.
>>>
>>> Now Buildout is used by Zope,Plone,Django and many
>>> other projects.  May be someone can write an entire
>>> book about Buildout :)
>>
>> BTW, if volunteers are coming forward.  I can coordinate
>> and provide all details required for updating the documentation.
>
> I have created a wiki to document Buildout:
> http://wiki.zope.org/buildout/BuildoutWiki
>
> We will move documentation to official site as it becomes matured.
> Let's see how it works.
>
> The format of wiki is reStructuredText so it would be easy to move
> to Sphinx. To create a wiki link, you can use two square brackets:

Thanks for trying to get this going.

I have a few suggestions:

1. Focus on a few key needs. I think some small efforts could yield
   big pay offs.

2. I think the most important need is for a clear *concise*
   introduction that describes what buildout is for, and it's
   philosophy and one or two simple examples. I think this could be a
   modest effort.

   The essential content for this likely already exists in one of the
   many buildout presentations on buildout.org.

3. For reference, the existing buildout doctests aren't completely
   horrible. :) They could be improved a lot with not too much effort
   by:

    - Converting them to use manuel
    - Commenting test cases that detract from the documentation.

   The idea is not to remove any tests, but to hide tests that detract
   from the documentation and make the remaining ones more readible.

Jim

--
Jim Fulton