Re: [Suggestion] Wikify the docs - Discussion!‏

[Guillaume Joutel <guillaume joutel insa-lyon fr>]

Hie,

I'm certainly not the greatest user of this mailing list but the idea of 
wikifying the docs sounds very well to my hear.
Errors or problems pointed out by sledge hammer are really time 
consuming for me and if I can help future users to not loose to much 
time I would do my best.

The only technical question begged by this idea is : won't it be much 
harder to do this wikification than trying to correct problems ?

sledge hammer a écrit :
> Hi,
>
> I had a crazy thought today. Why not wikify the docs? Why you ask? 
> Well, the docs aren't complete and many functions need more 
> documentation or code examples. Moreover, as I have been using the 
> online docs for almost a year now I have noticed some problems. Such 
> as(but not limited to):
> 1. Most of the enums don't have documentation. A reader needs to open 
> the gtk+ docs and find the corresponding documentation.
> 2. There are some function-documentation that tries to link to soming 
> else that doesn't exist. This obviously occurs from the automatic 
> generation of the docs. This "problem" is somewhat rare, but exists.
> 3. Many function-doc is just copy&pasted from the gtk+ docs but 
> doesn't correspond 100% to the C++ bindings
> 4. Quite a few minor typos
> 5. Quite a few functions don't have documentation just because the 
> their name documentes them(eg Gtk::Widget::show())
> 6. Signals often don't have a documentation or they have a poor one. 
> Almost always they don't tell when they are emited or what they mean etc
>
> These all can't be fixed by a few people(the devs). But they can 
> certainly be spotted by the users of the API. These users could on the 
> spot correct the problem. The problem usuallyhas an obvious 
> solution(eg a typo). This has the benefit that the bug tracker is not 
> cluttered for doc-requests. Also the changes take effect immediately 
> and you don't have to wait the person in charge of the docs to make 
> the change. Furthermore, these problems by their nature are really 
> small and insignificant so noone goes out of their way to post a bug 
> report on the tracker. Although small and insignifacant they take more 
> time to discover an answer(eg browse the gtk+ docs to see what an enum 
> does). I personally have discovered many problems like these but I 
> didn't file a bug report because it would be time-consuming.
>
>
> Also if the docs are wikified, other people may post a useful example 
> code for a function, thus enriching the docs. Or they may explain 
> different use-cases(maybe pointing in a separate wiki page). Also the 
> users, could insert "see also links" that point to relevant functions, 
> eg in Gtk::Widget::Show() "see also" would be Gtk::Widget::Hide(). 
> There could be other improvements also.
>
>
> Please post your opinions on the matter. I would like to hear from 
> regular users too. Maybe the devs will make this change if enough 
> people want it! Thanks for your time.
> ------------------------------------------------------------------------
> Νέα Windows 7: Βρείτε τον κατάλληλο υπολογιστή για εσάς. Μάθετε 
> περισσότερα. <http://windows.microsoft.com/shop>
> ------------------------------------------------------------------------
>
> _______________________________________________
> gtkmm-list mailing list
> gtkmm-list gnome org
> http://mail.gnome.org/mailman/listinfo/gtkmm-list
>