Re: [pygccxml-development] pyplusplus status

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

Roman Yakovenko wrote:

>On 7/25/06, Matthias Baas <ba...@ir...> wrote:
>  
>
>>Allen Bierbaum wrote:
>>    
>>
>>>What do you think about:
>>>- Moving the development of this documentation to a "live" site online?
>>>     I can contribute a wiki backend or server space for any other
>>>method that people recommend.
>>>[...]
>>>      
>>>
>
>I see, I have no choice, sorry: I don't like this idea. I think that
>the project is still young and correct documentation is vital for it success. Before every
>release I review all documentation and update. I check almost every
>piece of code, that is still works. 
>
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.

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. The code is 
still the absolute authority with the generated reference API being a 
close second.  We should only use the online tools to document things 
that are relatively stable or describe frequent questions.
- Protecting against spammers and bad editis can be difficult.  What I 
have been doing to prevent this is to use a blacklisting plugin that 
detects mis-use and autobans people and also allowing change 
notification so people that are interested get notified of every change 
on the wiki (this allows review).  It is also still possible to read 
through the documentation before a release to make sure it is accurate.
- In code documentation still needs to be updated.  This is not a 
replacement for that.
- I don't know of a great way to make a stable copy for release.  One 
idea would be to create a wiki page that includes all the documentation 
pages for the tutorial into a single page.  Then this page could be 
saved out as html and packaged with the release.  There are also wiki 
plugins that could help support something like this but I have not used 
them before.  (see: http://twiki.org/cgi-bin/view/Plugins/PublishContrib)

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
- 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.... (it reminds me of coding in python vs. coding in C++ :)
- Live docs allow the user community to work together to create, edit, 
and comment on documentation. 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/
- 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
- It removes a huge bottleneck in the documentation and feedback process 
because the suggestions and comments don't have to be routed through a 
developer with commit access.
- It is possible for users to see the latest documentation without 
checking out the source code.  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?

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.

-Allen



>Boost has wiki, almost every week, they
>have to rollback few pages back, because of spammers.
>
>  
>
>>Then what are you waiting for? :)
>>I'm definitely in favor of having a wiki for pyplusplus related stuff
>>(even if it is not considered to be the official source for
>>documentation). The recent logging modifications (+ a small HOWTO how
>>log messages can be written to a file, etc) are already an example of
>>what I would have liked to add to the wiki.
>>    
>>
>
>Now, when this functionality is finally implemented, yesterday I begun to write
>documentation to it. You can find the initial version here.
>
>http://svn.sourceforge.net/viewcvs.cgi/pygccxml/pyplusplus_dev/docs/documentation/feedback.rest?view=markup
>
>I'll be glad if you could continue this document.
>
>Please tell me why do you want use wiki instead of writing documentation?
>Is there something that I can do with an obstacle?
>
>  
>