[pygtk] Documentation

[standa.]

Gustavo J. A. M. Carneiro wrote:
> On Dom, 2006-09-03 at 19:02 -0300, Johan Dahlin wrote:
>   
>>> So I have some tips about documentation:
>>> 1. it would be great to have an option to enter my thoughts, tips, misunderstandings right on the documentation page. Like PHP does. I think it's good. IE i needed to create dialog box. It was simple. In last paragraph (dialog class) - ... you can call run()... Fine. Dialog appeared, but there is no info, what to do next. How to make it disappear. All what I was missing was - for closing the dialog call function destroy(). It took me 30min. I'd like to add this info to docs (or pass this info to maintainer of the docs), but how? Creating account in bugzilla and filling bug report is too "heavy" process to take just for sending this little info. Sending an email to some email account created for this purpose would be easier, but still not as simple as form directly on the docs page. And I think, there is plenty of "little informations" that could be collected from users.
>>>   
>>>       
>> Yes I agree totally. It's be very nice to have a comment system on top 
>> of the current
>> documentation.
>> It's a bit problematic though, because you need to be able to persist 
>> all the comments
>> somewhere and you also need to make sure that it's easy to update the 
>> original documentation against the one which is built from cvs.
>>
>>     
>>> 2. While viewing info about classess there are viewed only methods and signals from the displayed class. But there are a lot of other methods form ancestors. It would be great to have all methods displayed in place. Like javadocs has. I think it's good. There could be problem, because som classess has a lot of methods and displaying all ancestors methods altogether can make a really long list. But there could be solutions how to accomplish it.
>>>   
>>>       
>> This would be very interesting as well, I'm not sure how it would be 
>> solved in practice.
>> Perhaps generating an alternative view, similar to javadoc would be an 
>> option for that.
>>
>> Both of these are worthy goal, but unfortunately none of them are 
>> trivial to implement, they'd require someone with time and motivation to 
>> go ahead and solve them.
>>     
>
>   See:
> 	http://live.gnome.org/LiveDocumentationEditing
>
>   
The point with documentation is to have a lightway way to send a
feedback to documentation maintainer(s) about some difficult parts or
tips related to specific pages/methods/arguments.


Thoughts:

- form inputs:
text - actual text
contact - not mandatory. Who should be contacted for clarification of
the text if needed. The authot of the post.
documentation page - (may be hidden) where exactly user was when he/she
filled the form

- there is no need for form to be directly visible on each page. There
would be just link and after clicking on the link the form would be
displayed either making form visible or by displaying new page with
(only) the form in it.

- every form is sent as an email to someone who is able to
   * incorporate the change into CVS or
   * who has direct acceess / contact  to somebody who is able to make
commits to CVS or
   * has an experience with creating patches and knows where to send
them (bugzilla?)
There is no automatic processing. Every change is done by human being. I
can't imagine automatic processing of the posts.

- I don't suppose to append this comments directly to the documentation
page but incorporate them into existing text. IE to make some info more
descriptive or to add some typical / common use of some feature in a
description of the class etc. Or if there is some more complex example
sent, put it into tutorial.

- some dedicated page may exists. All collected posts would be displayed
on the page with status of their processing. Accepted (how) / Not
accepted (and may be) reason why / ...

End of thoughts.


I don't know how documentation is maintained right now.
I suppose the proper way to make a change in documentation is to fill a
"bug" in bugzilla.
I don't know how many comments would be collected from the proposed form.
I don't know how much time could take on average each month processing
collected posts.

standa.