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!

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.