Monthly Archives: July 2018

DeveloperExperience

Developer Center Initiative – Meeting Summary 26th July

Leave a comment

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.

Uncategorized

Re: GUADEC Report

Leave a comment

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

DeveloperExperience

The Developer Center Initiative – Call for Participants

2 Comments

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!

DeveloperExperience

GUADEC18 Developer Center BoF Part 3: Challenges

Leave a comment

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.

DeveloperExperience

GUADEC18 Developer Center BoF Part 2: Possible Audiences

Leave a comment

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.

DeveloperExperience

GUADEC18 Developer Center BoF Part 1: The Developer Experience

9 Comments

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.

Uncategorized

GUADEC 2018: BoF Days

3 Comments

Birds of a feather flock together..

Monday went with engagement BoF. I worked with Rosanna to finalize the annual report. Please help us proofread it! I have also started collecting information for the GNOME 3.30 release video. If you are  a developer and you have exciting features for GNOME 3.30, please add them to the wiki. The sooner you do it, the happier I am.

Tuesday went by with the GUADEC BoF where we reflected on the conference as a whole and identified pain points and how we might improve them. Afterwards, glorious sandcastles were made at the Sandcastle BoF.

Wednesday morning I hosted the Developer Center BoF. It was a productive session where we identified what the developer experience currently consists of, the possible audiences, the variables coming into play, challenges, stakeholders who might be interested in its development and developers centers by other projects equally sized like GNOME. I’ll write a blog post summarizing the BoF soon.

In the afternoon me and Sam recorded audio in preparation for a possible Flatpak Release Video and Britt helped mastering it. I also helped the GUADEC Video Editing BoF with generating intros and outtros for this year’s GUADEC videos.

GUADEC is over and I am going home tomorrow. But there is a lot of stuff coming up in July for me. The GNOME annual report needs final review and publishing. We plan to have a developer center call in the by end of July (if you are interested in participating, please  mark your availability here.) We also expect to make a Hackfest for the Developer Center after FOSDEM. And I have the GNOME release video and Flatpak release video on my to do list.  GUADEC has been productive and I hope I can work on some of these projects in my free time (help is welcome!).

Thanks to the local team and all volunteers at GUADEC for a great conference!

 

 

Uncategorized

GUADEC 2018 Day 3

Leave a comment

Day 2 ended with a guided tour inside the Alcazaba of Almería.

Surprisingly, the castle tour featured an exciting belly dance and a bonus theater show starring GNOME’s legendary actors.

Day 3 had plenty of talks like the other days – but I decided to spent it working with Britt on the annual report.

Lastly, lightning talks took place by the end of the day, I spoke about my experience starting Open Source Aalborg (Download PDF Slideshow).

(all picture are CC-BY-SA 4.0, by me)

Uncategorized

GUADEC 2018 Day 2

2 Comments

Yesterday ended with a cozy party at the beach with opportunity for swimming in the ocean and in ice cream. Today, GUADEC Registration and one conference room moved to a new building.

I volunteered as chair conference room all day and saw many exciting talks with many topics such as System76, GJS, Translation and testing.

We had breaks with tea, coffee and delicious eaties sponsored by Slimbook and Codethink.

GUADEC was also in today’s local newspaper – we finally made it to mass media folks!

The conference day ended off with GNOME’s Annual General Meeting which is a great opportunity to reflect on GNOME vision and the amazing progress we are making to achieve it.

(All pictures are CC-BY-SA 4.0 and taken by me)

Uncategorized

GUADEC 2018 Day 1

1 Comment

At 8.30 i took off Thursday morning to start my journey to Almería. I took the plane to Madrid and had 1 hour to get hold of a taxi and reach a train taking me to Almería. There I was fortunate to meet Julian and Tobias who were hacking on Fractal and making mockups.

We arrived 10.30 in the evening at Civitas for pre-registration. I met up with my roommate Niclas, who is also from Open Source Aalborg  (Denmark) like myself. The day after started with tomato spread on bread.

Everyone gathered to get with the bus and we arrived to the university.

GUADEC was kicked off in a big hall with Nuritzi, the GNOME Foundation president on stage.

After watching a couple of talks I had volunteered for the infodesk and helped giving attendees lunch tickets.

Of course, I also brought the socks and the GUADEC team had this year’s GUADEC t-shirts for sale.

This wraps up todays’ events for me. I’ve already managed to chat with many GNOMEies again and I’m looking very forward to the next days!

(All pictures are CC-BY-SA 4.0 by me).