At this year’s GUADEC lightning talks I spontaneously announced and arranged a Developer Center BoF (Birds of a Feather) session. We were six attendants who met together Wednesday the 11th July. I think it is important that we communicate our doings to the rest of the community, so I will make a few short blog posts based on our meeting notes and my own thoughts on the subject.
What is this all about?
We are several people in our community who are dissatisfied with the developer documentation experience, in particular if you use bindings and are unfamiliar with GNOME terminology and API. The GNOME Developer Center supposedly provides “all the information that you need to create fantastic software using GNOME technologies” but is not maintained and looks dated. There has been discussions on improving the experience previously, but I feel it’s time to take inspiration from our gitlab migration and organize a proper initiative now (wiki page coming soon).
At the GUADEC 2018 BoF we conducted a bottom-up analysis of our current developer experience which can help lay some foundation for informed decision making. It consisted of the following:
- Define what we talk about when we talk about the developer experience.
- Define possible audiences and identify our primary audience.
- Identify the challenges our current users experience.
- Evaluate other developer center experiences, their structure and experience.
- Create short-term and long-term plans for the developer center and scope it.
In this blog post, Part 1: The Developer Experience, we will define the current developer experience.
What constitutes our developer documentation experience?
What follows is an overview of important sources of GNOME documentation we are aware of. Searching and finding information in these sources constitute the current developer documentation experirence. It might be easy to think that we should only concern ourselves with the developer center itself, but in practice, developers search much wider for help than that. This is a list of things we identified at the BoF and additional information that later came to my mind:
- The Application Development Overview (gtk-devel-docs)
- The C API Reference (generated by gtk-doc)
- Getting started with GTK+ 3 in C, (maintained by Matthias in the GTK+ repository)
- A list of various Guides (from the HowDoI pages in the GNOME wiki)
- The Human Interface Guidelines (maintained by Allan Day in gtk-devel-docs)
- Various blog post tutorials by developers in our community.
- Devhelp provides API reference (maintained by Sebastian)
- Builder (API reference, Auto-completion..) (maintained by Christian Hergert)
- A PDF book by Sebastian on the GTK/Glib platform.
- Video tutorials on GObject by Christian Hergert and on GTK+ 3 by me.
- The Newcomer guide: How to contribute to GNOME’s Apps
- Introductory Tutorials, fx this one on PyGObject,
- The PyGObject API Reference, Javascript API Reference, Rust bindings other binding documentation.
- Documentation on shared components which is generally used in GNOME/Linux, fx FreeDesktop API, Application distribution such as Flatpak, etc.
- The GNOME and GTK+ tags on Stackoverflow.
This paints a picture of a very scattered experience, but obviously, the intention here is not that the developer center should unify absolutely everything. However, by knowing what is out there we can in the future make more informed decisions on what the GNOME Developer Center should host itself and what external sources could be useful to link to (and which we can consciously leave out).
The next step in our analysis is then to understand the possible audiences which I will cover soon in Part 2: Audiences.
Your input?
Is there other important information which has been vital for your GNOME developer experience? Helping understand what our current experience consists of is useful information so we can be more conscious when designing the next generation developer center. Leave a comment here or in this gitlab issue.
If you are interested in contributing to this initative, join the call next week or join the hackfest in February. More information on both of these coming soon.
I have been tinkering with GNOME apps in the past, before the great change to Meson and Builder. While it was easy to dive in, given nice introductory articles, the Big Picture wasn’t clear at all. For example, I wanted to get/set configuration values and ended up with GConf even though dconf was already out and used. Then there were infrastructural difficulties: how to get the autotools to install the GConf/dconf schema, how to install custom icons properly, etc. Presumably it’s easier now with Meson and Builder (dunno).
Looking just now at the gtk-devel-docs, it leads me right to GSettings, which is good. And it even sports a build integration section, but only covers autotools, not Meson. IMHO, a good way to improve developer experience would be to unify the projects build system in favor of Meson and have more Big Picture documtentation (e.g. how to build your app with proper GSettings integration).
Oh, and I think GNOME should embrace Rust and minimize C to the greatest extent possible.
Thanks for your input! I agree. Having this list of things we already have can help us understand holes in our documentation that we need to fix. I’ll soon blog about other “Holes” we need to cover and other issues regarding the developer center we ought to fix.
Debugging… especially if you are new to debugging itself. Maybe in that case it should point to some good resources on the topic. And then build upon that to teach to properly debug an application in GTK.
It’s something that once learned well, it makes your developer life way easier. But is not exposed as something important with GTK. There are tutorials here and there on how to make simple apps, but not on what to do when your creation crashes and burns to the ground.
And also, concurrency, threads and asynchronous operations with GTK and your binding. There are some small examples, but there are not really articles that are more thourough. It could be easier.
I remember that I didn’t know what was the best approach to create a multi-window app, like Evince. There is a lot about single window applications, but I missed some guidelines there.
To use osd widgets like the ones in Totem or Documents, I had to go read source code. I didn’t found anything about that. And I implemented it through trial and error.
That’s all I can think of right now.
This is excellent feedback. It will be useful pointers when we start looking for what content is important to write. Thank you!
Hello! I’m late, what I’m missing in the list is especially the Gtkmm tutorial[1] fort the C++ bindings.
And while the support for MacOS is important and has problems as far as I know, I strongly miss a good explanation how to install Gtk/Gtkmm based applications on Windows. Figuring out the required libraries is easy, but on top you need the loaders.cache stuff and the libraries from gdk-pixbuf and you shall include all icons. Or just some? I reduced it to “some icons” to make the application smaller. Some has tried to sum it up[2].
I think we weakest point of Gtk is nowadays the support for Cross-Plattform, in the days with Nokia and Sun it was already much better. GNOME and Gtk are in a better position on Linux, if applications on all plattforms can be written for it. I just increases the likeliness that Gtk is even considered by an developer.
[1] https://developer.gnome.org/gtkmm-tutorial/stable/
[2] http://www.tarnyko.net/repo/gtk3_build_system/tutorial/gtk3_tutorial.htm
PS: I think the mobile improvments for the Librem are a really good thing for Gtk itself.
Thanks for the input and links! Just out of curiosity, what was it that you wanted to use Gtk for in C++? What sort of application were you making?
The application allows to use a smartcard-terminal, it was required that the application should be easily runnable and leightweight. Furthermore the possibility to run on Windows and Linux was important and probably Mac in the future. The required hardware access made C/C++ a natural friend and being lightweight.
A desktop application to access a smartcard terminal, it’s running on Windows and Linux. Probably MacOS, but I just don’t know it, I have no Mac. Because of the hardware access, the requirement for an easy runnable and small application with a low footprint either C or C++ where the natural choice.