Developer Center

This is a call for anyone interested in discussing the future of the GNOME developer center.

Subject

We will talk about:

• Defining the goals of the developer center.
• Defining what the developer center should NOT be.
• Defining how we can make the developer center a maintainable piece of infrastructure.
• Make a short-term plan and long-term plan.
• Defining a minimum viable solution which is extensible.
• Systematic Evaluation of technical directions we could take and design directions we could take.

Audience

Anyone interested in:

• working on GNOME web infrastructure.
• works on language bindings / documentation.
• interested in writing documentation.

Organizers

• BastianIlsø

Participants

People who are planning on or are expected to attend:

• BastianIlsø

Attendees:

• BastianIlsø

• Evan Welsh

• Ken VanDine

• Philip Chimento

• AviZajac

• Patrick Griffis

Agenda

Hackfest Planning:

• Finding a date
• Who is interested

• https://wiki.gnome.org/Hackfests/DeveloperCenter2019

• Draft from 2018: https://wiki.gnome.org/BastianIls%C3%B8/DevX18

Meeting Notes

Maybe colocated with FOSDEM? Either Thursday before (Friday is GNOME Advisory Board meeting) or Monday after

We need a minimum number of people interested in attending, in order to make it an official hackfest

• Interested: Bastian, Evan, Ken, Philip, Avi
• Possibly: Patrick
• Ask later: Sri, Michael Hall, Allan

What is the developer experience now?

• The newcomer guide: How to contribute to GNOME Apps
• Application Docs: How to develop apps
• GNOME Technology: API References

• Docs for developing libraries & components (JHBuild...)

• How do I...?

Audiences:

• 3rd Party App Developers
• GNOME Stack Developers
• GNOME App Developers
• Designers
• Interns
• Newcomers
• Extension Developers
• Theme Development
• Distro Developers

Variables that come into play:

• Familiarity with the GNOME stack
  • Existing GNOME developers know what component can solve their needs and want to search for information about them.
  • New developers don't know what components to look for to achive what they want and need to be introduced.
• Familiarity with programming
  • Ranging from "I don't know anything", "I know some Javascript", "I know C" to "I have developed GNOME before".
• Differing Language Capacity
  • We have people for whom English is not their first language
• Learning Styles

Challenges

• Fragmentation in our documentation
  • Users has to go to different websites to find unofficial documentation which might be outdated or misleading.
  • The newcomer guide is hosted on wiki.gnome.org, the GJS API reference lives in devdocs.io, dev.gnome.org has outdated documentation.
• Lack of documentation targeted to specific audiences
  • Where do I go if I am a third party app developer and want to develop my own app?
  • ...a newcomer who does not know programming so well?
  • ...an extension developer who wants to develop a new GNOME Shell extension?
• Too many choices
  • Should I use Python, Javascript or C to develop? Does it have consequences, which I choose?

• Maintenance of Docs & Infrastructure

  • The previous instance has been unmaintained for years. How do we ensure that the infrastructure could keep itself maintained?
• Difficulty editing/writing docs
  • The current developer center does not allow easy editing which is necessary to maintain the docs.
• People use 40 different programming languages
  • Even if we choose a specific language to support, people in practice have language preferences.
  • Even if fx Javascript bindings were first class citizen, people will eventually need to use C for more advanced features.
• Discoverability
  • The current developer center documentation structure makes it difficult to find the tutorials.
  • Some tutorials live on other websites.
  • The developer center's search does presents results from GTK+3, 2 and GTKMM and it is unclear.
• Unofficial/oudated docs
  • When the GNOME developer center doesn't provide up-to-date documentation, people go to other websites and the websites might provide misleading or outdated information.
• Communication channels
  • Newcomers have a hard time with IRC, it can be intimidating and isn't similar to the messaging apps that most people are used to

Involved Stakeholders:

• GNOME Builder (Flatpak, Meson)
• Documentation Team (?)
• Newcomer Guide Team
• Bindings Team (GJS, ...)

Examples of Good Documentation We Like

• https://jasmine.github.io/tutorials/your_first_suite

• https://jasmine.github.io/tutorials/custom_equality

• https://docs.unity3d.com/Manual/index.html

• http://bedrock.readthedocs.io/en/latest/index.html

• Bastian Ilso: Defining the Developer Center Initiative
  • Systematic Project Definition / Scope / Goals:

  • https://wiki.gnome.org/Initiatives/DeveloperCenter

  • Inspiration: https://wiki.gnome.org/Initiatives/DevelopmentInfrastructure

Useful Links

• Gitlab project:

  • https://gitlab.gnome.org/Community/DeveloperPortal (includes django framework)

• Telegram group link:

  • https://t.me/joinchat/ApyZTxJF3Bgj4EfNOm3X3w

• DeveloperCenter Whiteboard by AllanDay

  • https://wiki.gnome.org/Design/Whiteboards/DeveloperCenter

• Existing "Solutions" for API reference generation

  • https://github.com/hotdoc/hotdoc

• Philip has requests that hasnt had response for more than a year..

  • http://www.sphinx-doc.org/en/stable/

• Patrick told that Builder has implemented support for generating Sphinx docs

  • http://devdocs.baznga.org/

• GJS has generated documentation in DevDocs

  • https://pygobject.readthedocs.io/en/latest/

• PyGObject has generated documentation in readthedocs

  • https://developer.gnome.org/gio/stable/GInputStream.html

• GTK-Doc based generated html API reference.

  • http://lazka.github.io/pgi-docs/

• PyGObject generated documentation

  • https://valadoc.org/

• Vala generated documentation

Interested in writing documentation

• Bastian Ilsø
• Evan Welsh
• Avi Zajac
• Patrick Griffis
• Philip C

Notes: Never use the words "this is simple" and similar phrases in documentation, as it comes across as belittling for people who are struggling with a concept.

Action Steps

Announce the Developer Experience Hackfest for Monday after FOSDEM (Bastian Ilsø)

Arrange a follow-up call about the developer experience hackfest.

Blog Posts

Blog posts about the session:

• GUADEC18 Developer Center BoF Part 1: the Developer experience by Bastian Ilsø Hougaard

• GUADEC18 Developer Center BoF Part 2: Possible Audiences by Bastian Ilsø Hougaard

• GUADEC18 Developer Center BoF Part 3: Challenges by Bastian Ilsø Hougaard

BoF Notes