This is Part 3 of a blog post series summarizing the Developer Center BoF. See also Part 1: The Developer Experience and Part 2: Possible Audiences.

When we talk about improving GNOME and the infrastructure around it, we often quickly skip right ahead to talking about solutions (“The developer center is missing feature X“). However, before we can jump ahead into an informed discussion about solutions, we need to agree what it is we want to solve, that is:

• What kind of challenges does our audiences face when they look for documentation currently?
• What kind of challenges do our community face when they want to contribute to our current documentation?
• What consequences do these challenges have for the developer experience?

Defining the challenges should be possible for us now since we have already defined the possible audiences and what we mean when we say our developer documentation.

Challenges

The following highlighted challenges are based on the list of challenges identified in the BoF  and my own reflections:

1. The documentation is fragmented

The documentation we have currently lives in multiple places.  While our C documentation currently lives in developer.gnome.org, our GNOME Newcomer Guide is hosted on wiki.gnome.org. The GJS API Reference lives in devdocs.io.  The PyGObject Manual lives in readthedocs.net.  Documentation fragmentation refers to the issue that developers have to end up going to different websites  than developer.gnome.org and  potentially end up finding unofficial documentation which might be outdated or misleading.

2. The documentation branding is inconsistent/out of date

Our developer center uses outdated visual looks which is inconsistent with our other infrastructure (wiki, website, etc.). Documentation hosted outside developer.gnome.org also use different branding and visual style which makes it hard to distinguish maintained, official documentation from unmaintained documentation.

3. It is unclear from the landing page what documentation the Developer Center contains.

The Developer Center hides its documentation behind four large categories on the home page. The category naming is ambiguous (“Guides” vs “Application development overview”) and does not give you a proper overview of what our documentation constitutes of. The front page navigation categorizes content, instead of trying to create on-boarding paths for specific audiences and in worst case our audiences apply guesswork to find what they are looking for.

3. It is unclear what documentation is up to date.

Our documentation being as scattered as it is, makes it difficult to assess what of our documentation is good and actively maintained for our readers. By searching documentation on developer.gnome.org you can still find documentation for GTK+ 2 and many guides has not been updated for years and may therefore be deprecated.

4. Our audiences use many different programming languages.

Much of GNOME is written in C and has bindings to  many languages which is both a blessing and a curse. Our developer center currently provides API references in C, and various tutorials in Python, Javascript, C++ and more. Supporting the many different programming languages grows the complexity of unifying the developer center and provide a good experience everywhere. However, those language bindings are maintained because there are people out there who use them and prefers them over other languages and this will probably not change. Some of these people have also spent many hours writing documentation for binding languages on external websites and made external API references hosted outside GNOME Developer Center. I think these people are important for us to reach out to, when we discuss this challenge.

5. Which programming language should I choose?

This is related to number 4. For certain audiences such as third party developers and newcomers, the large language support can lead to confusion. Ideally this could be purely up to preference, but in reality some language bindings are more developed, maintained , tested and documented than others.

We should keep in mind that while some of our possible audience confront this challenge, many others in our possible audience already have language preferences, which I think is why proposing solutions related to this issue in the past has presented heated debates.

6. No on-boarding path to Developer Center from GNOME.org

GNOME.org has paths for getting involved with GNOME and downloading our platform through distributions, but we have no on-boarding path for developers who wants to start developing apps using GNOME technology.

7. Maintenance of infrastructure & documentation

Currently, the Developer Center infrastructure and documentation suffers from low to non-existing maintenance. It’s a sign we need to take serious. Do we need lower the barrier to contributing to the developer documentation? What can we do to make the infrastructure easier to maintain? The underlying issue here likely also ties into why we now see new GNOME documentation hosted on other websites by different maintainers powered by different underlying technologies. I think this challenge needs both thinking from a technical point of view (how we might support editing multi-language documentation and auto-generated documentation) and an organizational point of view (assigning maintainership, reviewing our docs, aligning visions).

Your Input

What do you think constitutes a major challenge for the Developer Center? I’ll review the comments made to this blog post and have also started an issue on Gitlab you can comment on.

Follow the effort

This was the last part of my blog series on the Developer Center GUADEC BoF. On Thursday 26th July, 16:00 UTC we will have a developer center call and if you are interested you can see the agenda and sign up here. Here are a few links if you wish to follow the ongoing efforts closely:

• Watch the Developer Portal Repository.
• Find us in the #docs channel and subscribe to gnome-doc-list where we will send call invitations, meeting summaries and framadates.
• Sign up for the hackfest (currently draft) which will happen in February after FOSDEM 19.
• There is also the DeveloperPortal group on Telegram (PM me to get the link).

The next step for us will be to come up with short-term and long-term plans for the developer center and the call on Thursday will be the first step towards this. If there is interest, I will write a blog post summarizing our progress.