This is a call for anyone interested in discussing the future of the GNOME developer center.
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.
Anyone interested in:
- working on GNOME web infrastructure.
- works on language bindings / documentation.
- interested in writing documentation.
People who are planning on or are expected to attend:
- Evan Welsh
- Philip Chimento
- Patrick Griffis
- Finding a date
- Who is interested
Draft from 2018: https://wiki.gnome.org/BastianIls%C3%B8/DevX18
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...?
- 3rd Party App Developers
- GNOME Stack Developers
- GNOME App Developers
- 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
- Differing Language Capacity
- We have people for whom English is not their first language
- Learning Styles
- 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
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.
- 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
- GNOME Builder (Flatpak, Meson)
- Documentation Team (?)
- Newcomer Guide Team
- Bindings Team (GJS, ...)
Examples of Good Documentation We Like
- Bastian Ilso: Defining the Developer Center Initiative
- Systematic Project Definition / Scope / Goals:
- Gitlab project:
https://gitlab.gnome.org/Community/DeveloperPortal (includes django framework)
- Telegram group link:
DeveloperCenter Whiteboard by AllanDay
- Existing "Solutions" for API reference generation
- Philip has requests that hasnt had response for more than a year..
- Patrick told that Builder has implemented support for generating Sphinx docs
GJS has generated documentation in DevDocs
- PyGObject has generated documentation in readthedocs
- GTK-Doc based generated html API reference.
- PyGObject generated documentation
- 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.
Announce the Developer Experience Hackfest for Monday after FOSDEM (Bastian Ilsø)
Arrange a follow-up call about the developer experience hackfest.
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