All posts by Bastian Ilso Hougaard

Behind the GNOME 3.30 Release Video

The GNOME 3.30 release video was announced earlier this week on Youtube. Additionally we now have a GNOME channel on Peertube by suggestion of Greg.

This marks the 10th release video for me which I find super exciting. The videos has been excellent platforms for me to learn and allowed me to reach a consistent level of production quality. For instance, check out the GNOME 3.12 release video which was my first video production.

Production moved to Gitlab

With each video I experiment with new workflows. Traditionally I have been involved in every step of the production apart from the voice-over with very few opportunities for others to step in and contribute. With Gitlab’s powerful issue tracking system, this no longer needs to be the case. This has meant that I can spend more time on production in Blender and spread out the other aspects of production to the GNOME community. The work done ithisn the GNOME 3.30 Release video is covered by the following Gitlab issues:

  • The 3.30 Release Video Main Issue provides an overview of the 10 main milestones in producing the release video (11 participants) with regular updates from me on how production was progressing.
  • The 3.30 Content Gathering Issue collected information from GNOME developers on what had changed in apps and organized how those changes should be screen recorded (25 participants / 16 tasks).
  • The 3.30 Video Manuscript Issue used the collected information to create a narrative around the changes resulting in a manuscript Karen and Mike could produce a voice-over from (6 participants / 3 tasks).
  • The 3.30 Animation Issue gave an overview of the animations which needed to be produced to match the manuscript and screen recordings (3 participants / 12 tasks).
  • The 3.30 Music Issue provided general guidelines to Simon on production of the music and in the future it could provide opportunity for community members to provide additional input.

The sheer number of participants should give you an idea how much big a relief opening the production has been for me. I still account for managing the production, animating the majority of the video and having a finger in most tasks, but it helps me focus my efforts on providing a higher quality result.

Future Challenges

There are still aspects of the production which are still not public. For example, I am not sharing drafts of the video prior to production which creates less feedback in the animation process and makes it harder for translation teams to provide adequate thistranslations in some cases. This is simply to avoid leaks of the production prior to release which has happened in the past and is a big pain point, considering the sheer effort everyone is putting into this. For next time I will experiment with releasing early stage work (animatics and sketches) to see if this could be a meaningful replacement.

For developers, there were many questions and issues regarding the process of screen recording which is documented in this issue. The production sets requirements to resolution and FPS which is not always possible for developers to meet due to hardware and software limitations. I would like feedback from you on how you think this went and how we might be able to improve the tooling. Let me know!

Finally, we have had two unforeseen events which caused the video to be delayed by 5 days. First, we are currently unable to convert subtitles for the release video due to a bug in po2sub. Secondly, the delay was caused by me and Simon having busy schedules close to the release date which is always hard to predict. However, the general policy here is to rather release late than release something unfinished. I am confident that as the Gitlab workflow matures and we improve how work is scheduled, these delays can be minimized.

Conclusion

I hope you enjoyed this insight into the release video production. If you are interested in participating or following GNOME 3.32 Release Video production, subscribe to the 3.32 Release Video Gitlab issue. Thanks to everyone who contributed this cycle!

Developer Center Initiative – Meeting Summary 23rd August

On Thursday the 23rd August we held another Developer Center meeting. Unfortunately due to unforeseen circumstances I was late to this meeting, but I will try my best to report on the events.

We are on the verdict of making a technological decision and we have two proposals which currently is in debate, namely HotDoc and Vuepress (for now, Michael has expressed that he is currently unsure if he is able to commit the necessary time to work on the Django instance). This meeting we listed and agreed on a set of criteria, weighted after importance. These criteria has root in the list of challenges which was covered in a previous blog post. The purpose of having a list of criteria is to reach consensus on how to prioritize features in the proposed instances when we judge them.

The next section will describe a few highlighted criteria that we weighted. You can find a full list of criteria here. Any input is welcome on the Gitlab thread.

Criteria Examples

Note: The following criteria descriptions are mainly my own understanding, so I’d like to refer questions to the Gitlab thread.

Number of developers/activity
It is clear by now that all the test instances imply a workload that needs to be taken on, before we can reach something minimum viable. When we evaluate VuePress and HotDoc and others, we need to consider how much commitment behind them and how much work power they will require for continued development.

Translatable – natural and programming languages
The ability to keep documentation in multiple programming languages and human languages.  One of the main points of this initiative is to unify our API references and guides into a single place and both VuePress and HotDoc has support for this. The second challenge is to provide natural language translation abilities too and integrate it with the existing translation tooling in GNOME. Regardless of proposal, that is something all instances would need extra plumbing to achieve.

Vision of the site fits how the tool works
This is specifically about how easy it is to achieve the developer center experience we want using the given tool. A content plan for the developer center has not yet been completely worked out, but we have an initial structure in place from Allan’s design which gives good pointers here.

How easy users can contribute and provide feedback
It is highly important that the solutions provide a pathway to contribute to their contents, ideally with as little steps between identifying a problem to re-writing and getting the changes reviewed and applied. In both the case of VuePress and HotDoc there has been demonstrations in previous meetings that they can provide “Edit in Gitlab” links to take you straight to Gitlab’s text editor on the file itself.

Site search for documentation
Site search will be one of the main ways of exploring the documentation on the website. The performance, precision and extensibility of the website search is going to be important. A point was also raised in the previous meeting that the website search might need to be able to provide search results from external websites too (think e.g. GTK+ on StackOverflow and more..) as much documentation is likely to be still floating around on other websites (fx. on ReadTheDocs).

What’s next

Discussion on the Vuepress, HotDoc, Django and Sphinx threads are still open and I’ll encourage everyone to present questions if any. The HotDoc thread in particular has seen some notable activity since last meeting as Thibault and Mathieu has conducted an automatic test port of the gnome-devel-docs over to Markdown (see demo and discussion thread).

The next meeting will be held in conjunction with LAS GNOME around the 9th September 2018 either at 15.00 UTC or 16.00 UTC (to be announced soon in the etherpad / mailing list). Subscribe to the gnome-docs-list to get meeting announcements and summaries. Moving forward, I would be interested in hearing the opinion of those involved in this initiative on the proposed technological solutions. It would also be useful to begin organizing the documentation writers and develop an initial content plan.

New Videos & New Opportunities

Flatpak 1.0 has released which is a great milestone for the Linux Desktop. I was asked at GUADEC whether a release video could be in place. In response, I spontaneously arranged to produce a voice-over with Sam during the GUADEC Video Editing BoF. Since then, I have been storyboarding, animating and editing the project in Blender. The music and soundscape has been produced by Simon-Claudius who has done an amazing job. Britt edited the voice-over and has lended me a great load of rendering power (thanks Britt!).

The Flatpak Video
https://www.youtube.com/watch?v=jDVCITRWGgs

The GNOME 3.30 Release Video is also on its way, with release due at September the 5th. The video will be the 10th release video I have been involved since i started (time flies!).

Future

From 2019 I’ll be looking for full-time opportunities to continue working with UX, User Onboarding and Motion Graphics in FOSS (see also my website). This summer I graduated as MSc. Medialogy at Aalborg University in Denmark. Since then, I have been working for Aalborg University over the summer to design Learning Analytics UI. In parallel I have enrolled in The Drawing Academy to engage full-time in the visualization craft until 2019.

My past six years of world-wide remote collaboration to GNOME have been greatly rewarding. Apart from the release videos, I have designed the GNOME Newcomer Guide with Carlos, working on Polari UX in Google Summer of Code and most recently engaged in the Developer Center Initiative.

I am on the lookout for short-term or long-term occupation which allow me to continue my contributions in the GNOME and FOSS ecosphere.  Don’t be afraid to get in touch! :-)

Developer Center Initiative – Meeting Summary 8th August

Yesterday we had the second meeting about the Developer Center Initiative. We had 14 attendees with participation from HotDoc, GJS, Purism, Builder and more.

The primary topic for this week was to let developers review and demonstrate website prototypes based on different technologies. This is where we would like your opinion too! We are particularly interested in choosing the solution which..

  • ..can unify our documentation and API reference.
  • ..is maintainable.
  • ..is easy to contribute to for writers/developers.

I would like to thank everyone for working on the presented solutions! The test instances are not fully functional of course, but they  prove that it’s a possible direction we can go if we choose to.

Django

The Django instance is based on the software stack used previously for the Ubuntu Phone developer portal (An example can be seen from the Wayback Machine). It is a dynamic CMS which uses minimal Bootstrap CSS with possibility to extend its functionality using plug-ins. Users registered in the Django instance can edit documentatioGNOME documentationn using the built-in WYSIWYG editor and the documentation can be searched in all programming languages through a unified search. It can be setup for multiple human languages with possibility to set fallback languages. It is also possible to create redirects and stage changes before they are published.

The Ubuntu Portal used language-specific scripts to import API documentation by reading documents generated for each language. For GObject documentation, an importer would be needed to be written. One possibility could be to modify HotDoc to generate the documentation into Django’s database.

One of the things discussed in relation to Django was whether a dynamic website would be necessary (versus static). It creates a heavier load but could offer some extor HTMLra possibilities like comments/code attachments or generated code packages.

HotDoc

HotDoc generates a static website which can become a replacement for the whole Developer Center. It can generate API reference itself from GObject and has unified search. It links languages together so you can easily switch from one programming language to another. HotDoc allows us to specify subprojects meaning that library maintainers can generate documentation on their own and the documentation can then be positioned in HotDocs sitemap.  It is meant to replace GtkDoc this way. Documentation is written in Markdown and is editable through “Edit in Gitlab” links.

The project has not been developed further so much lately since there are not so many users and the current users of HotDoc have most of the features they want. Mathieu and Thiblahute gave examples such as the PiTiVi documentation and the GStreamer documentation (work in progress). Mathieu assessed that to use HotDoc as developer center, the existing documentation would need to be ported to MarkDown. He has implemented a PanDoc reader which could be usable for this purpose. Furthermore, libraries would need to be ported from GtkDoc to HotDoc.

VuePress

Evan has built a GJS Guide for his internship based on VuePress which is used by VueJS. It supports multiple human languages via directory overrides and has search. Documentation is written in MarkDown which VuePress compiles into tutorials with table of contents, editable through “Edit in Gitlab” links. This could also be usable for API reference since GObject-introspection now can generate MarkDown and HTML from GtkDoc and make links in-between documentation.

Currently there is no example of API reference ported to VuePress – the test instance currently has it in DevDocs. To generate the API documentation, a CI runner would need to have GObject-introspection generate each language into a directory and create a dropdown component in VuePress to switch between directories. Some extra CSS styling would need to be done to make it conform to Allan’s theme. It currently does not live in GNOME’s Gitlab due to slow CI for Gitlab Pages.

Sphinx

Sphinx was also on the radar, but we did not have time to discuss it in detail. Currently no test instance exists either, except for the PyGObject documentation which is written in ReadTheDocs. Christoph Reiter who is one of the documentation maintainers has shared his thoughts on using Sphinx for the Developer Center in the Gitlab discussion linked above.

Next Steps

With the demonstrated instances and detailed discussion we hope to make a decision on a specific technology at the next meeting. If you have questions or comments on the presented technologies, please let your voice be heard in the linked Gitlab discussion threads! It will help inform the final decision-making.

Finally, check out the  framadate we have running for arranging the next meeting in 2 weeks. See you there!

Developer Center Initiative – Meeting Summary 26th July

This blog post summarizes the topics discussed at the Developer Center Call hosted on 19th July.

1. Hackfest Announcement

A hackfest is planned to take place the 4th and 5th February 2019. We are currently looking for a venue.  If you can help with this, please let add a comment in this Gitlab issue.

1.b Other Events

Libre Application Summit is happening from 6th to 9th September and Sriram is planning on coordinating a BoF-style session about the Developer Center (more info coming soon). If you are interested in this, please contact Sri (or comment on the Gitlab issue).

Shaun mentioned that Write the Docs Cincinatti happening on August the 18th to 22th could be a good venue for making a content plan, gap analysis and more.  If anyone is interested in coordinating to make this happen, please contact me or write to the gnome-doc-list.

2. Developer Center Design Status

Allan has made an experimental tentative design in 2016 which tries to make something viable based on the existing developer content we have today.

Note: This design does not yet define details like the exact wording, the exact landing page contents, nor the exact visuals. We would need a web designer to take a look over this.

But Allans design puts the initial structure in place which can be used as foundation for new Developer Center and iterated upon.

  • API Reference section
  • Design Guidelines section
  • Tutorials section
  • Distribute section

3. Developer Center Prototype Status

3.a Website Prototype

Michael Hall has been working on a test instance based on Django which was previously used for the Ubuntu Developer Portal. Michael and Sri is currently getting a test instance hosted at GNOME in collaboration with Andrea Veri. For the previous Ubuntu Developer Portal, Michael had made a Django app which pulled in multi-language API references and updated the portal every night.  The Django instance also supported multiple human languages with fallback behavior. It requires more server infrastructure but it could in the long run could support dynamic content such as Q&A for developers, comments on tutorials and code snippet uploading.

There was some discussion about whether a dynamic website system is needed or if a static website system designed for documentation could be enough for our needs. Evan Welsh was looking into using his GJS API Reference project in conjunction with Vuepress and will present a proof-of-concept for the next call.

EDIT: To be clear, there has not been made a definitive technological choice yet, but an evaluation will start soon.

3.b API Reference Prototypes

The current C API documentation as we know it, is hosted at the Developer Center.

HotDoc is a potential tool for source code inspection which should be investigated, but Philip and Evan (GJS developers) reported issues contributing to the project. Instead they wrote a DevDocs adapter which works by scraping G-I files. Patrick reported that the PyGObject API reference work using a similar scraping technique, but is based on Sphinx.

Allan argued that if necessary, we could in the very short-term try to stitch something together from different websites, so the initiative does not fall short due to the technical challenge in unifying these technologies. Attempting to solve everything from the start has been one of the reasons to that the initiatives has fallen short in the past.

4. Written Documentation Status

The current Human Interface Guidelines (HIG) and the Developer Tutorials are hosted in the gnome-devel-docs repository.  The documentation is written in Mallard and edits are made by pushing updates to the gnome-devel-docs git repository. Allan still maintains the HIG today but the developer tutorials are in a mixed state between “still relevant” and “out of date” and lacks editorial control.

There was discussion about moving the documentation to MarkDown or Restructured Text which could also ease editing since Gitlab’s integrated editor supports it and Django supports it.

Next Developer Center Call

There is currently a framadate running to find the date for the next call, which will take place in 2 weeks’ time. The agenda so far is:

  • Evaluation of Vuepress and Django test instances.
  • Short-term plan for the API References.
  • Short-term plan for documentation writing.
  • Migration plan for Human Interface Guidelines / other content.

Participation welcome!

If you are interested in helping with the website or the documentation writing, join the next call or sign up in this Gitlab issue.

Re: GUADEC Report

Hi Sébastien,

I am truly sorry if the discussion we had on developer documentation has upset you and contributed to your negative experience at GUADEC.

1. From my point of view there was nothing going wrong between you and me.

I remember we had a productive discussion at GUADEC. We found out that we have different opinions. For example, I you told me that you prefer books and written tutorials. I remember telling you that I like video tutorials. I think that in a future developer center, there can be space for both (See [1]).

2. I have not reported you to the code of conduct committee.

I remember an evening we sat at a café outside Civitas and you told me there was negative talk about you. When I heard this I got really confused because it came out of nowhere for me. I did not recall anyone saying “..asshole developers” in my presence at any point during GUADEC. I was being honest back then when I told you this.

I do remember that we went out to eat together on the evenings after our developer documentation discussion. We did not have so much to talk about but I thought it was natural. I am not are really the type of person who naturally can “set the line of conversation”. :-)

If you have any further doubts or questions about my behavior, please let me know.
If you had the impression that I was attacking or avoiding you, I really apologize deeply, this was never my intention.

-Bastian

[1] https://gitlab.gnome.org/Community/DeveloperPortal/issues/12

The Developer Center Initiative – Call for Participants

Hi everyone,

The Developer Center Initiative had a call after the GUADEC BoF. We had 13 participants which I think is a great start. We need the manpower too!

I’m going to summarize our call meeting in a blog post soon, but first I want to introduce the people and their interests. Note: this list is so far only consisting of people who participated in the call. You can sign up below!

Call Participants

Developers

People interested in developing the Developer Center and technology surrounding it:

  • Philip is the GJS maintainer and has previously had test beds for GJS API References up and running.
  • Evan who has developed the GJS API Reference as part of his Google Summer of Code project.
  • Michael has developed previous Developer Portals in Ubuntu and has set up our Django repository.
  • Patrick is involved with GNOME Builder and is interested in improving tooling for our developers.

Writing Documentation

People interested in writing or maintaining documentation in the Developer Center:

  • Bastian Ilso (me) maintains the GNOME Newcomer Guide with Carlos and I am interested in writing tutorials for developers and making video tutorials.
  • Patrick is interested in writing documentation and has lots of inside-knowledge on fx GNOME Builder.
  • Sriram who has previous experience in technical writing.
  • Allan maintains the GNOME Human Interface Guidelines and plans continue doing so.
  • Antonio expressed interest in writing tutorials and possibly translating them later on

Documentation Team Key Contacts

People from the Documentation Team who has expressed interest in advising the initiative:

  • Petr is head of the Documentation Team for Users and Sysadmin and has knowledge to share related to structuring and managing documentation.
  • Shaun has stayed with the Documentation Team for a long time and has been involved in past efforts on the developer documentation.

Tobias, Adrien and Heather from Purism were also present in the call and they expressed interest in investigating possibilities for sharing documentation with GNOME in the future if there are places where it makes sense. I think it’s a great idea!

Call for Participation

Working on Developer Docs requires people with many different skillsets. Are you interested in helping out writing the new developer tutorials or updating the existing ones? Maybe helping with the Developer Center website? If you are interested in this effort, sign up by commenting on this Gitlab issue.

I’ll be back in a soon with a meeting summary and the announcement of the next Developer Center call. See you!

GUADEC18 Developer Center BoF Part 3: Challenges

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:

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.

GUADEC18 Developer Center BoF Part 2: Possible Audiences

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

Hi Again! As promised I will now cover our discussion of possible audiences at the GUADEC Developer Center BoF.

Possible Audiences

“Developers” can mean many things. There are several subclasses of developers we need to take into consideration so we can decide how to scope the developer center. Deciding a primary audience will become important later to take design decisions and align our vision. Note that I say “primary” – to create a good developer experience we still need to ensure a good story for other audiences we care about. In this list, one person may fit into several audiences and all of the audiences will need to be well defined (e.g. with a description):

  • GNOME newcomers (interested in contribution)
  • Experienced GNOME stack developers (fx library developers)
  • Experienced GNOME app developers
  • Third party app developers (unfamiliar with GNOME technology)
  • Interns (think GSoC or Outreachy)
  • Shell Extension developers
  • GTK+/Shell Theme developers
  • Distribution maintainers
  • People who are new to programming
  • Programmers from all over the world
  • Programmers who prefer video tutorials
  • User Interface Designers (?)

At this point we can start identifying some constraints which our users’ behavior and goals depends on:

  • What they wish to accomplish (an app, an extension, a design)
  • Their familiarity with the GNOME stack.
  • Learning preferences (text tutorials, video tutorials,..).
  • Programming language preferences
  • Spoken language preferences
  • and possibly more..

We need to consider which of these we think is important in the short-term and in the long-term. Simultaneously, we need to consider the maintainability of the Developer Center and its content too. This is a list of possible audiences – eventually we should decide on short-term priorities.

Among the six attendees at the GUADEC BoF there was fairly wide interest in having the GNOME Developer Center cater to application developers and especially third party developers. I know that me and Carlos are also interested in having the developer center provide a good experience for newcomers, who share’s their unfamiliarity with GNOME technology and terminology with third party developers. In general, I think catering to application developers is a good approach as more users of our technologies benefit our ecosystem.

What’s Next

By knowing what our developer experience of (Part 1) and with the possible audiences in mind (Part 2) we can start consider what challenges our current experience encounters, which we ought to solve. I will cover this in my last part of this blog post series, Part 3: Challenges.

Your Input

If you have any additions to the lists above or comments, let us know! Comment on this blog post or on the related Gitlab issue.

GUADEC18 Developer Center BoF Part 1: The Developer Experience

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:

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.