Commenting online docs [Was: Howto retrieve selected font size from GtkFontButton]

[Stefan Kost <ensonic hora-obscura de>]

Nelson Benítez León schrieb:
> 2008/12/3 Christian Dywan <christian imendio com>:
>   
>> Am Wed, 3 Dec 2008 12:31:23 +0100
>> schrieb "Nelson Benítez León" <nbenitezl gmail com>:
>>
>>     
>>> 2008/12/2 Stefan Kost <ensonic hora-obscura de>:
>>>       
>>>> Nelson Benítez León schrieb:
>>>>         
>>>>> 2008/12/2 Sven Herzberg <herzi gnome-de org>
>>>>>           
>>>>>> http://bugzilla.gnome.org/show_bug.cgi?id=562998
>>>>>>             
>>>>> Ok, thank you!,  I was about to suggest that, because I thought
>>>>> gtk_font_button_get_font_name just returned the font name, thanks
>>>>> for this doc improvements, it would be easier if the online docs
>>>>> permited user contributed notes.
>>>>>           
>>>> Let me chime in as the gtk-doc maintainer. While that sounds like a
>>>> good idea its not that simple. If someone has a complete proposal I
>>>> would be willing to help doing it. Problem is to feed the comments
>>>> back into the docs which are in the sources.
>>>>         
>>> I don't think comments need to go back to sources, comments would be
>>> in mysql indexed by the symbol name they referred to (function name,
>>> class name, signal name, etc) and there would be a php page that will
>>> combine the gtk-doc html with the comments and present that to the
>>> user.
>>>       
>> The problem with that approach is that not everyone is using the online
>> documentation. For one, it requires a perfect network connection, which
>> you may not have if you're traveling or somewhere without permanent
>> broadband. Plus it is obviously slower and less convenient to search,
>> compare to 'devhelp'. Hence I agree with Stefan's assumption that
>> comments should be folded back into the sources.
>>     
>
>  I think nowadays, thanks to library.gnome.org, most people use online
> documentation, it's way more practical because you don't have to
> install any package, it's always up-to-date, it has a good google
> search and you can open the information in several tabs with your
> browser.
>   
I use devhelp all the time. I only use library.gnome.org, when I am in a
meeting using my window laptop :)

> But I don't think this is an online vs offline documentation question,
> I'm talking about adding a feature to the online docs, if people want
> later to add that feature to the offline docs they can, just save the
> html output of the online docs to disk in some browseable format.
>
>   
It would really need an administrative iface too to process the comments.
>> Maybe a compromise would be that there is a page that lists all user
>> provided pieces, so that developers can easily go over the list, decide
>> what's useful, file a documentation bug if appropriate, and also remove
>> false information if needed. It would add a bit of maintanance but if
>> it can be integrated with bugzilla logins/ permissions, it might be an
>> overwieable overhead.
>>     
>
>  I don't like this approach, it requires manpower, and what is worse,
> someone who decides what is useful and whatnot, that is subjective, I
> prefer there's an official documentation with no comments, and the
> online documentation with the possibility to add comments. Just like
> in www.php.net/docs.php where you have the online documentation with
> comments, and if you choose to download the documentation (eg. to
> consult it offline) then you get the official version with no
> comments.
>   
And ther eis a lot of noise too. I agree that its better than nothing.
One good thing would be if people can also rate the comments. If we
would have a view for developers, they could look for high rates
comments, take them to the sources
and remove the comment.

My biggest issue is that this is a webapp that someone would need to
write. Any volunters? Next years GSoC?

Stefan
> _______________________________________________
> gtk-devel-list mailing list
> gtk-devel-list gnome org
> http://mail.gnome.org/mailman/listinfo/gtk-devel-list
>