Re: [pygccxml-development] pyplusplus status

[Matthias B. <ba...@ir...>]

I think we are intermingling two separate questions that, in my opinion, 
should be treated independently:

(1) Is it reasonable/useful/desirable/cool to have a pyplusplus related 
wiki where *users* can add any information they deem useful when dealing 
with pyplusplus?

(2) Should the above wiki also be used as the primary source for the 
official pyplusplus documentation?

My previous answer to Allen's posting was dealing with the first 
question and I'm still in favor of such a wiki.
As to the second question, that's entirely up to Roman as this 
influences the way he creates the documentation. If he doesn't feel 
comfortable with using the wiki for the official documentation, then I 
accept that and it's no problem with me. But if the answer to the second 
question from above is "no" then I don't see why the answer to the first 
question also has to be "no".

Basically, I agree with all points that Allen has made. The main 
advantages of a wiki for me are the following:

- *Anybody* can contribute and it's as little hassle as it can get (an 
arbitrary web browser is the only tool that is required) => It reduces 
the threshold of whether a user will decide to contribute or not.

- You get immediate feedback on how the page looks. You can use 
formatting such as bold face, italics, switch the font, use tables, 
images (if the wiki allows it), link to other pages, etc.

- Wikis are quite common nowadays which means chances are that a user 
already has used a wiki before. And if you've used one wiki you know how 
to use other wikis as well => the above threshold is lowered even some 
more as a user doesn't have to learn new tools

- When there's the option to register you get the chance to get notified 
about changes to the wiki. This means you have the option to always be 
informed about the contents of the wiki and what changes have been done. 
On a regular web page you would have to maintain (and publish) a 
changelog to achieve the same thing.

- A wiki would also be a nice place for adding information about the 
stuff in "contrib" which is no official code and won't be mentioned in 
the official documentation anyway.


Roman Yakovenko wrote:
>> 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 

If I've interpreted Allen's mail correctly then he has already 
volunteered to maintain the wiki and even host it. So it doesn't mean 
any extra work for you.

> or insure that all that is written there is 100 % correct. 

That's the beauty of a wiki, whenever some user encounters something 
that is not correct he has the option to edit the page and simply fix it 
himself. :)

> The maintainer of the wiki can subscribe to
> svn-commit list and update the wiki according to the changes.

Sounds good in theory, but I'm pretty much sure that this won't work in 
practice (unless you find someone who has really a lot of time at hand).
But anyway, this is not required at all. A wiki would never replace the 
reference manual generated by epydoc and having a wiki also doesn't mean 
that we can drop doc strings.

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

Why do you think so?

1) A wiki is just a tool for writing text and making it available to the 
public. It's up to the person who is writing the text whether the text 
is correct or not. If a person can write a correct tutorial in Word, 
Emacs or whatever then that same person can also enter a correct 
tutorial into a wiki.

2) As already mentioned above, if some other users notice something that 
is not correct they can simply fix it themselves.

3) How do you explain the success of Wikipedia? ;)

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

How many such mails have you got so far? Personally, I have already 
entered text into wikis but I have never sent a piece of documentation 
to an author of a software.
Writing an email doesn't have the advantages of a wiki and the above 
mentioned threshold that a user has to overcome before deciding to 
contribute something is higher (why should I bother someone personally 
just because I want some modifications to the documentation which is not 
meant to be edited publically?).

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

I agree that registration is a minor nuisance. But I wouldn't mind 
registering if 1) the site tells me that this is only to protect the 
site from spammers and 2) I only have to provide a user name and 
password and no other personal information.
On the other hand, registration has the advantage that you can customize 
the wiki to your own personal taste and you can be notified about 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.

 >>> users==community
True

See? :)

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

Not everyone is familiar with subversion and knows how to build the 
documentation (or is willing to do all that just to check if there's a 
new FAQ item). Pointing your web browser to a particular page is much 
easier.


So the bottom line is that I would answer my initial question (1) with 
"yes, definitely" and leave the answer of question (2) up to Roman 
(which he has already answered with "no").

- Matthias -