Re: [pygccxml-development] pyplusplus status

[Roman Y. <rom...@gm...>]

On 7/25/06, Allen Bierbaum <al...@vr...> wrote:
> Roman Yakovenko wrote:
> You do have a choice, that is what I was waiting for.

:-)

>  I wanted to see
> if everyone could agree to it being a good idea or a bad idea.  I do not
> plan on creating or updating a pyplusplus wiki documentation area
> without Roman's support.  If Roman is not on board with it, then it is
> bound to fail.

I think you exaggerate a little. I don't want to maintain it or insure
that all that is
written there is 100 % correct. The maintainer of the wiki can subscribe to
svn-commit list and update the wiki according to the changes.

> Roman: Could you describe the reasons you don't want the tutorial  to be
> user-editable online?  (so far I think your list is)
>
> - Removes the documentation from the source code.
> - How to make sure it is accurate (spammers, bad users,
> misunderstandings, etc)?
> - This will prevent the in-code documentation from being updated.
> - How do we make a "stable" copy for a release?
>
> I agree with some of this but I think the benefits out weight the costs.
>
> My response to these issues are.
> - Online is only meant for the tutorial, how-tos, and faqs.

In my opinion tutorials could not be written using wiki. I just don't
see how it
could work.  Tutorials is short, clear, well formulated and 100%
correct document.
Wiki can not achieve this.

> Now as to why we want to work on tutorial documentation in this way, I
> can not speak for Matthias, but here is my reasoning:
> - Making the documentation live make is very easy for anyone (not just
> people with commit access) to write and update documentation

I don't count this as argument. You can open any email client, write a
documentaiton and send it to me. I will integrate it in a day or two.
Every one who contributed to pyplusplus is mentioned.

> - Using live documentation in a wiki form allows for immediate editing
> of documentation.  You can make a change in text format and immediately
> see the result.  You don't have to use an html editor or even a text
> editor.  You can just be sitting there reading the documentation, think
> of something that is missing, and add it.  This a very short development
> loop....

This is another problem with the wiki. In order to prevent spam you will
force user to register himself. I don't have statistic, but as for me, I use
registration only when I absolutely need.

> - Live docs allow the user community to work together to create, edit,
> and comment on documentation.

pyplusplus still does not have community :-(. It does have users, but not
community.

> For example plone does this here:
> http://plone.org/documentation/how-to  and php allows comments in their
> docs here: http://www.php.net/manual/en/

Python does it too.

> - We can make a live knowledge base of issues, howtos, and faqs that
> really describe what people are trying to do and how they have
> accomplished it

Here you are right. Wiki can provide good feedback.

> - It is possible for users to see the latest documentation without
> checking out the source code.

Here you are almost right too, but it has nothing to do with wiki. I
don't update
documentation on site between releases, because I want the functionality to
become stable. This process takes few month.

> For example, what good is an FAQ that has
> an entry about how to do something with a release if you don't see it
> until the next release?

I think, that the answer is obvious: use code from Subversion. Anyway
my point here is that this item does not worse any effort.

> As you can tell, I am biased towards having on-line tutorials and
> howtos, but like I said above, I won't do it without Roman's approval
> and support.

As I said, will not be an active maintainer but I will do provide a help.

As for me wiki will be good in a future. But before starting wiki, I
think pyplusplus
should have good documentation.

-- 
Roman Yakovenko
C++ Python language binding
http://www.language-binding.net/