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,
- 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.
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.