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.