I don't think that documentation truly exists. You can read the Gtk+ documentation and the Cairo documentation, but that really only tells you what the APIs do

I don't think that documentation truly exists. You can read the Gtk+ documentation and the Cairo documentation, but that really only tells you what the APIs do in the grand scheme, not why they were added, what problems they solve, or the gist of how to get best perf. Most of the time when you're writing new widgets you only care about drawing lines, placing icons and laying out text, for which Gtk+ has fast higher level mechanisms and you should use those (see gtk_render_line(), gtk_render_icon(), gtk_render_layout() and their friends). When in doubt, use the newer widgets and functions (the ones with the latest "Since:" annotations), since they have usually replaced older functions with worse performance or behavior. If you're lucky, those new functions will even document why you shouldn't use the old function anymore... The general theme of working with Gtk+ is "do as the library does", as it's mostly been written and maintained by people who know these things through decades of experience and that code can help guide you towards avoiding bad behaviors (like the famously bad StackOverflow-style toy example code that creates an image surface, renders some clock or gears vector image to it imperatively, and then setting that image surface as your widget cairo context's source and rendering the whole image to your widget and wondering why you can only get 10 fps vs using gdk_window_create_similar_surface() to make your offscreen rendering target, splitting your drawing up into the "clock face background" and the "clock hands foreground" pieces, and only re-rendering the hands as they move or even prerendering all of the different hand positions to another offscreen buffer and blitting the pieces as necessary and suddenly realizing you can get hundreds of FPS easily.) Sadly all of this means source diving a lot of the time. And it can be hard, especially in cases where you want to stray off the beaten path and do a completely new widget design - you will want to find and make friends with great GNOME people as they can really mentor you through these more complicated widgets until you get your legs under you. The toolkit as a whole is moving towards a model more like that of modern browsers, where widgets are conceptually smaller and simpler and composite widgets and layouts are more of what you actually have to maintain. (A good example of the latter is looking how complicated the current code in GtkSpinButton was, compared to how conceptually it could be a much simpler composite widget that only handles the key/button events between a pair of buttons and a text entry). This shift in design is a boon for many application developers, but it can mean really struggling if you want to write or maintain complex applications with components such as drawing canvases (e.g. the GIMP) and layered cross-process rendering (I used to work on VMware Workstation...) You can help! Document your findings as you learn, write patches against these libraries and their documentation, get it reviewed and committed. The Gtk+ folks are not scary to work with, just very opinionated.