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!

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.