Re: [pygccxml-development] pyplusplus status

[Allen B. <al...@vr...>]

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

I have to respectfully disagree here.  I have seen a wiki work for this 
type of thing and work very well.  I think you too would believe it once 
you see it. :)

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

There are bottlenecks here though:
- Someone has to check out subversion and know how to edit the rest files
- They have to edit it and generate the docs
- They then have to send it to you and wait for it to be integrated.

In my experience, wiki just makes this much faster.  What do other 
people think here?

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

True, but already people have to go through at least as much trouble as 
registering if they want to get access to the svn docs and if they want 
to edit and submit changes.

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

I think it could have a community if we start building one.  Until we 
build it, there won't be one.

>
> [cut]
>
>> 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.

One other way to look at it is that by putting it on the wiki you could 
get a lot of help on the documentation.  I know I would use the wiki as 
my primary documentation for pyplusplus and would add to it all the time 
while using the API.  It sounds like there may be some other people that 
would be willing to help out with this as well.

So in a way, it could make your life easier by letting us help you write 
the documentation while you are still concentrating on fixing lingering 
bugs and documenting the code.

But enough of what I think, what do other people think?  Are there other 
users on this list that would contribute to a wiki for documenting and 
extending pyplusplus?

-Allen