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

[Lyle Underwood <lyleunderwood gmail com>]

I'm usually not a fan wiki-style documentation, but I have noticed a lot
of information lacking. The most frustrating for me was the timing of
the signals not being in there.

I really like the structure of the current documentation, and I find
wikis difficult to navigate. There's not usually a nice hierarchical
structure to a wiki. I think that streamlining the process of reporting
these problems, or a new system for users to submit additional
documentation incorporated into the current solution would be ideal.
Going full wiki seems like it would lose a lot of the great
functionality this thing already has.

What's more, I'm fairly certain that the current documentation is
generated directly from comments in the source code. Now, I haven't made
a submission to an open source project before so I don't know for sure,
but can't any user submit a patch with changes to the documentation?
Obviously, this is a bit too intimidating for Joe User. 

I'm really not at all qualified to recommend a solution, but these are
just my opinions based on my experience with both styles of
documentation.

On Wed, 2009-12-16 at 18:40 +0200, sledge hammer wrote:
> 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: Βρείτε τον κατάλληλο υπολογιστή για εσάς. Μάθετε
> περισσότερα.
> _______________________________________________
> gtkmm-list mailing list
> gtkmm-list gnome org
> http://mail.gnome.org/mailman/listinfo/gtkmm-list