This year’s GUADEC took place in Greece – six days vacation with plenty of time to dive into GNOME again (I missed you!).

When I last posted in January, I talked about my new full-time employment at Aalborg University as Research Assistant. Unfortunately it has left me little time to continue release videos or developer documentation. At GUADEC 2019, I decided to re-visit the developer documentation issue, with a different approach to contributing to a better experience.

The “ideal” GNOME developer portal has been the conception of a top-down approach: Creating a coherent structured platform, which collects documentation in one place. The challenge is that providing platforms require a lot of legwork and coordination – something which we in the past months have not had. So until we have it, I have been wanting to focus the time I had at GUADEC on a bottom-up approach: Providing GNOME developer documentation, where new developers look for them: on “Google” (and other web search engines). Arguably, people employ several strategies to find answers to questions, but my own experience is that searching the web remains consistently one of the most prominent strategies to get answers in relation to programming and app development.

The Bottom-Up Approach

The bottom-Up approach to developer documentation is the idea to:

1. Identify areas which lack documentation.
2. Provide that documentation on a location, which is highly likely to be found when searched for.

Concretely, during GUADEC 2019, I followed this approach through the following means:

1. I began programming my own simple GTK application called ‘Podium’ in GNOME Javascript / GJS.
2. I searched the internet when I ran into unknown errors, unknown concepts or API in GNOME technologies.
3. If I found the answer, I could continue programming.
4. If I did not find an answer..
   1. I asked the question I had in my mind on StackOverflow, using the search terms I used.
   2. I asked experienced developers at GUADEC for help, and used the information to answer my own question on StackOverflow.

This way, I intended to fill in gaps in the available knowledge across the internet – which to me is an important initial documentation goal, which we still can do, until we have a well-structured, cohesive platform to migrate content to. Additionally it comes with the bonus that it can be done small-scale – and since I was developing my own GTK app, I had extra stakes in discovering the answer (and hence, writing the documentation necessary).

4 days later

Here are some quick browser history stats after working on ‘Podium’ for 4 days (excludes API lookups):

• I had in total, 18 GNOME development questions or challenges.
• To solve those questions, I have in total performed 30 web searches and navigated to 37 search results.
• 10 of the web searches led to readily available results which solved my problem.
• 8 of the web searches did not lead to results which solved my problem, and instead i had to ask on StackOverflow and/or get help from GNOME experts.
• As a side note, I also filed 9 issues (small bugs or enhancement suggestions) against gtk+ and gnome-builder during the process.

If you would like some more details (fx the gaps I had in knowledge and my search terms), I compiled a filtered spreadsheet. All in all, it was quiet productive documentation session – I got a little app out of it too!

Next Steps

I hope this can demonstrate that there is still a lot of possibility to contribute to better developer documentation. Humans share knowledge like this all the time, but the knowledge is easily lost in inpersistent and closed communication channels such as IRC/Matrix/Real life, which are not accessible to web search engines. I think we should strongly advice newcomers to post questions online – this way, we can accumulate questions, worded based on newcomers’ mental model, which become future migration paths to the tacit knowledge hidden in our APIs and application code. Might be worthwhile to investigate how to integrate this approach into future newcomer workshops?

Eventually, I would like to make knowledge further persistent by keeping it on a GNOME-hosted platform in the future. Discourse might be a candidate for us to store information like that, but at the moment GNOME Discourse topics does not seem to appear in web engine search results – (might be natural given that our instance is fairly new? not sure).

Let me end this blog post with links to the Q&A threads created:

• bwrap: execvp application: No such file or directory (GNOME Builder Flatpak)
• How to use GTK+3 GtkImage in XML *.ui files from GtkBuilder
• I added a gtk widget to the main window UI file, but it doesn’t show up
• How to get files from selected folder with GtkFileChooserButton?
• GtkFileFilter makes Gtk-WARNING **: invalid filter: invalid content type
• How to make the platform independent filepath slash “/” with GLib? (GJS)
• Scaling GtkImage based on Window Size