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 > [email protected] > http://mail.gnome.org/mailman/listinfo/gtkmm-list _______________________________________________ gtkmm-list mailing list [email protected] http://mail.gnome.org/mailman/listinfo/gtkmm-list
