Category Archives: DeveloperExperience

Developer Center Initiative – Meeting Summary 21st September

Since last blog post there’s been two Developer Center meetings held in coordination with LAS GNOME Sunday the 9th September and again Friday the 21st September. Unfortunately I couldn’t attend the LAS GNOME meeting, but I’ll cover the general progress made here.

Test Instances Status

In the previous meetings we have been evaluating 4 possible technologies namely Sphinx, Django, Vuepress and HotDoc. Since then, the progress made in the development of these proposals has varied considerably. We got feedback from Christoph Reiter on the feasibility of using Sphinx and currently there are no efforts going towards making a test instance here. Michael was unsure he could commit the time to the Django proposal and suggests instead either Vuepress or HotDoc. For this reason the Sphinx and Django proposals have been closed off for now.

HotDoc has lately seen a lot of development by Matthieu and Thiblahute. A rough port of the Mallard-based gnome-devel-docs was demonstrated at the LAS GNOME call, so you can now for example find the Human Interface Guidelines in Markdown. Of course, there is still a long way to go, but this is a good first milestone to reach and HotDoc is the first of all the test instances to reach it. Matthieu also gave answers to criterias formulated in my previous blog post.

The main concern of HotDoc has been maintainability and the general small scale of the community surrounding it. On the other hand, Evan appears to be busy and Vuepress haven’t received attention since its initial proposal. As the choice narrows, we intend to give the test instances a last small window of time to gain activity. Simultaneously we have started to focus the short-term future efforts on improving the HotDoc test instance with Matthieu and Thiblahute.

Initial Content-plan

The second item discussed at the meeting was an initial content plan. Prior to the meeting I worked out how this content plan could look like based on Allan’s initial design. This is a summary of the proposed short-term plan:

  • The API Reference will explorable through the current gtk-doc static HTML and External API references will be linked where relevant.
  • The HIG will be ported to Markdown and maintenance from there continues in Markdown, see next bullet.
  • The tutorials section would consist of hand-ported GNOME Wiki HowDoIs and auto-ported GNOME Devel Docs. The GNOME Devel Docs repository would be ported at once to Markdown and reviewed. An announcement to the GNOME Docs mailing list when this happens. From that point on, documentation writers would be encouraged to continue edits directly through the new test instance.
  • The Distribute section will initially link to Flatpak’s Developer Documentation.
  • The Technologies overview will link to the corresponding GNOME.org page.
  • The Get Involved page will link to the GNOME Newcomer Guide on the GNOME Wiki.
  • Finally there is the GNOME Development Guide section, but this I would personally rather propose to merge with Tutorials.

There are a lot more question marks and wish thinking concerning the long-term plan, but you can read and comment on both short-term and long-term content plans in the Gitlab issue.

Next Steps

I will soon open a new framadate for a Developer Center meeting. For those interested in helping with the HotDoc test instance, feel free to file issues against it or join the discussion in the HotDoc Instance proposal. Personally I will try to get HotDoc running locally on my machine and review the current site structure so it matches closer to Allan’s proposal. I will also try to help Thiblahute with writing a migration guide from GtkDoc to HotDoc.

Reviewing the ported GNOME Devel Docs material itself is still too early, but if you would like to contribute in other ways, let us know!

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.

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.

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.