All posts by Bastian Ilso Hougaard

GNOME Developer Documentation – Bottom-Up

This year’s GUADEC took place in Greece – six days vacation with plenty of time to dive into GNOME again (I missed you!).

When I last posted in January, I talked about my new full-time employment at Aalborg University as Research Assistant. Unfortunately it has left me little time to continue release videos or developer documentation. At GUADEC 2019, I decided to re-visit the developer documentation issue, with a different approach to contributing to a better experience.

The “ideal” GNOME developer portal has been the conception of a top-down approach: Creating a coherent structured platform, which collects documentation in one place. The challenge is that providing platforms require a lot of legwork and coordination – something which we in the past months have not had. So until we have it, I have been wanting to focus the time I had at GUADEC on a bottom-up approach: Providing GNOME developer documentation, where new developers look for them: on “Google” (and other web search engines). Arguably, people employ several strategies to find answers to questions, but my own experience is that searching the web remains consistently one of the most prominent strategies to get answers in relation to programming and app development.

The Bottom-Up Approach

The bottom-Up approach to developer documentation is the idea to:

  1. Identify areas which lack documentation.
  2. Provide that documentation on a location, which is highly likely to be found when searched for.

Concretely, during GUADEC 2019, I followed this approach through the following means:

  1. I began programming my own simple GTK application called ‘Podium’ in GNOME Javascript / GJS.
  2. I searched the internet when I ran into unknown errors, unknown concepts or API in GNOME technologies.
  3. If I found the answer, I could continue programming.
  4. If I did not find an answer..
    1. I asked the question I had in my mind on StackOverflow, using the search terms I used.
    2. I asked experienced developers at GUADEC for help, and used the information to answer my own question on StackOverflow.

This way, I intended to fill in gaps in the available knowledge across the internet – which to me is an important initial documentation goal, which we still can do, until we have a well-structured, cohesive platform to migrate content to. Additionally it comes with the bonus that it can be done small-scale – and since I was developing my own GTK app, I had extra stakes in discovering the answer (and hence, writing the documentation necessary).

4 days later

Here are some quick browser history stats after working on ‘Podium’ for 4 days (excludes API lookups):

  • I had in total, 18 GNOME development questions or challenges.
  • To solve those questions, I have in total performed 30 web searches and navigated to 37 search results.
  • 10 of the web searches led to readily available results which solved my problem.
  • 8 of the web searches did not lead to results which solved my problem, and instead i had to ask on StackOverflow and/or get help from GNOME experts.
  • As a side note, I also filed 9 issues (small bugs or enhancement suggestions) against gtk+ and gnome-builder during the process.

If you would like some more details (fx the gaps I had in knowledge and my search terms), I compiled a filtered spreadsheet. All in all, it was quiet productive documentation session – I got a little app out of it too!

Next Steps

I hope this can demonstrate that there is still a lot of possibility to contribute to better developer documentation. Humans share knowledge like this all the time, but the knowledge is easily lost in inpersistent and closed communication channels such as IRC/Matrix/Real life, which are not accessible to web search engines. I think we should strongly advice newcomers to post questions online – this way, we can accumulate questions, worded based on newcomers’ mental model, which become future migration paths to the tacit knowledge hidden in our APIs and application code. Might be worthwhile to investigate how to integrate this approach into future newcomer workshops?

Eventually, I would like to make knowledge further persistent by keeping it on a GNOME-hosted platform in the future. Discourse might be a candidate for us to store information like that, but at the moment GNOME Discourse topics does not seem to appear in web engine search results – (might be natural given that our instance is fairly new? not sure).

Let me end this blog post with links to the Q&A threads created:

GNOME at FOSDEM 2019

Earlier this month, the annual FOSDEM conference happened again at ULB, Bruxelles, Belgium. I had the opportunity to go there, man the GNOME booth, sell socks, and catch up with other GNOME contributors.

Prior to the conference I had booked La Chambre Haute, which is a great little rooftop apartment located in Etterbeek, around 1.7km from the FOSDEM venue. I arranged the apartment for sharing through the GNOME wiki and shared the apartment with fellow GNOMEies Florian, Tobias, Julian and Niclas. We had a really pleasant time there, including oriental cooking and hacking! I can recommend joining for FOSDEM 2020. ;-)

Me at GNOME's FOSDEM booth
Me at GNOME’s FOSDEM booth

At the FOSDEM booth we sold hoodies, t-shirts and lotsa socks. By Sunday we were almost out of stock for the socks, most socks remaining now being knee socks. At the booth I also got to see the Purism Librem 5 Dev kit running GNOME software – I’m excited to see how it’s coming along!

Thanks to GNOME Foundation for sponsoring the trip. See you next next year!

2019 – New directions

It has been a while since you’ve heard from me. My keyboard’s Q, W and E buttons broke, but that will not prvnt m from making som nois on this blog anyay!

Pencil and paper

Since August 2018 I have been attending a classical drawing course full time. The craft has given me a great foundation for understanding composition, value and color judgement and I feel much stronger in my ability to plan, judge and execute visual artwork. My hands are also much more willing to do what my mind imagines and my thought process has been thoroughly challenged and turned upside down by my teacher.

Click to find BastianIlso's studies on Pixelfed

You may click the picture above if you are curious to see some studies. All in all, I’m far from done with classical drawing and I still have much to learn. I have every intention of returning to the school and continuing my studies in the future!

Career

Back in August I posted about my finishing of my master’s degree and that I was looking for new opportunities. Since then I have been offered a position as research assistant at Aalborg University’s Interaction Lab which I after much consideration have accepted. This has since January 1st 2019 been my full time occupation and will continue to be until 2020. The department is nice and I’m happy to be surrounded by many bright heads around me I can discuss and learn from every day. I will mainly be occupied with HCI research around mobile interaction, virtual reality and health technology. Which brings me to a sadder point..

GNOME Release Videos Needs New Hands!

It’s hard for me to let go, but reason tells me that it is time to pass on the torch with release video production for the time being. 10 videos is a great round number and a good place for me to step down. None of them were ever a stand-alone project and I deeply thank everyone for their contributions, small and big! I’m far from convinced that I have hit the right magic release video flavor yet, but they require a large concentration of time that I no longer have on my hands to give. That said, get in touch if you are interested in being the next video production person! I will gladly supervise, pass on necessary details and give feedback in the process of it all. I’m unfortunately hard to get hold off on IRC/matrix these days, but quiet easy to get hold of on telegram and e-mail.

FOSDEM

This is not a goodbye post, let’s just make that clear. I’m going to FOSDEM to take care of the GNOME stand and I’m bringing lots of socks! I’m eager to meet all of you fellow GNOMEies again. I have arranged an apartment which I will be sharing with Tobias, Florian and Julian and I’m looking forward to it!

So all in all, lots of things. I’m in the middle of moving out of my student dormitory so there’s still stuff to do. Let’s see what else 2019 brings! Happy new year!

Developer Center Initiative – Meeting Summary 10th November 2018

The Developer Center Initiative is an attempt to reboot the developer center  based on a new modern platform. For more information, see my previous  blog posts.

It’s been two months since the last Developer Center meeting. In light of that I called in for a meeting last week to get a status of things. We discussed three items:

  • Changing the current state of the developer center.
  • The need for a physical meetup to reinforce spirits and get bulk work started.
  • Pending bugs and feature merges in hotdoc relevant for the developer center.

Developer Center State

Thibault currently holds a branch for gnome-devel-docs. The branch contains the old GNOME Developer docs ported to markdown. To ensure that no duplicate work happens between gnome-devel-docs master and the branch, the next step is to announce to relevant mailing lists that further contribution to the developer docs should happen in the gnome-devel-docs branch. Even more ideal would be to have the branch pushed to master.  The markdown port is not synchronized in any way with the mallard docs in master, so any changes to the mallard docs would require re-synchronization and that’s why currently editing ported markdown docs in the branch currently is a no-go for now.

Pushing the branch does imply that we initially loose translations though and most changes made to gnome-devel-docs seem to be translations these days with a few exceptions (mostly grammar corrections). Thibault and Mathieu expressed interest in supporting translated docs in the future, but it is a substantial amount of work and low on the todo list.

We agreed that I should try to get in touch by e-mail to the relevant mailing lists (including translations) and to individuals who contributed to gnome-devel-docs recently to hear their opinion before we proceed.

Hotdoc status

On the hotdoc side, Mathieu and Thibault explained that they have pending work from the GStreamer docs waiting to land and include in a new release.  There is also an ongoing feature request to support flexboxes through markdown syntax which would be nice to have if we want to align Thibault’s branch more closely to Allan’s mockup.

With help from Thibault and Mathieu I managed to get a local instance of hotdoc running. A few bugs were fixed along the way and I plan to blog post a getting started guide to get Thibaults branch running on your computer which hopefully in turn can be used to improve the existing documentation on hotdoc.

Hackfest plans

For the past two months activity in this initiative has been running low which signals to me that we need to meet together physically again. The meeting attendance this time was around 3-4 people. I am going to FOSDEM 2019 and if anyone else interested in the gnome developer center’s future are attending too, I’ll be happy to meet up during conference for a chat. If sufficiently many shows interest, we could also extend the conference a day, sit down and have a look at the state of things by then.

Otherwise, if someone out there could help providing venue/office space sometime in spring, I can try to gather the group of people who have shown interest so far and get a proper hackfest going.

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.

New Videos & New Opportunities

Flatpak 1.0 has released which is a great milestone for the Linux Desktop. I was asked at GUADEC whether a release video could be in place. In response, I spontaneously arranged to produce a voice-over with Sam during the GUADEC Video Editing BoF. Since then, I have been storyboarding, animating and editing the project in Blender. The music and soundscape has been produced by Simon-Claudius who has done an amazing job. Britt edited the voice-over and has lended me a great load of rendering power (thanks Britt!).

The Flatpak Video
https://www.youtube.com/watch?v=jDVCITRWGgs

The GNOME 3.30 Release Video is also on its way, with release due at September the 5th. The video will be the 10th release video I have been involved since i started (time flies!).

Future

From 2019 I’ll be looking for full-time opportunities to continue working with UX, User Onboarding and Motion Graphics in FOSS (see also my website). This summer I graduated as MSc. Medialogy at Aalborg University in Denmark. Since then, I have been working for Aalborg University over the summer to design Learning Analytics UI. In parallel I have enrolled in The Drawing Academy to engage full-time in the visualization craft until 2019.

My past six years of world-wide remote collaboration to GNOME have been greatly rewarding. Apart from the release videos, I have designed the GNOME Newcomer Guide with Carlos, working on Polari UX in Google Summer of Code and most recently engaged in the Developer Center Initiative.

I am on the lookout for short-term or long-term occupation which allow me to continue my contributions in the GNOME and FOSS ecosphere.  Don’t be afraid to get in touch! :-)

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.