New HIG website

The design team is keen to give our Human Interface Guidelines a refresh: they haven’t been updated in a while, and are outdated. The guidelines would also benefit from some realignment, to cover topics that haven’t been addressed so far, and maybe drop some sections which aren’t so useful.

If we’re refreshing the HIG, we’d also like to change how the HIG is written and published. The existing HIG is built using GNOME’s standard developer documentation infrastructure: it’s written in Mallard, is part of gnome-devel-docs, and is published online using library-web. Sadly, the result is that it’s hard to maintain, doesn’t look great, and isn’t very easy to navigate.

We need a HIG that is easier to maintain and develop. We also need an attractive website for it, which is easy to navigate. Obviously, we’d prefer to achieve these goals using the standard GNOME docs infrastructure, and to tightly integrate with the rest of the developer documentation. However, given the current state of affairs, the design team is inclined to develop our own website to host the new version of the HIG.

We’d be interested in discussing which web technologies to use, out of the box documentation hosting solutions, and how to integrate with the rest of the developer documentation. Or, if this kick starts a renewed effort to improve GNOME’s documentation infrastructure, then we’d be interested in that too.

10 Likes

Hi Allan,

There was a discussion at the Portland hackfest about moving the User Help and the System Administration Guide from library-web to Pintail. @pmkovar would have a better idea about the infrastructure required.

Mike

Also Shaun and Petr mentioned it here.

That sounds great. Please include a “Next”, “Previous” button that allows us to read continuously without “going back and clicking” . And an offline copy would sound great. What about an linter like thing, that examines our code or XML and suggests improvements? Im EXCITED!

Hi @mdhill! Pintail sounds interesting, although I wonder what it has to offer in this particular case.

I think the main option we’re considering at the moment is a statically generated website: that’d give us flexibility over the layout and appearance. I assume that it would allow us to use lightweight markup for the content, and have a familiar contributor workflow.

Does Pintail/Mallard have any advantages over that? Are there existing sites that use them?

That post passed me by - thanks for the reference @mdhill .

@ebassi : if there is going to be new infrastructure for the handwritten developer docs, then it would definitely be interesting to have the HIG included there. Or, if we were to set up a new site for the HIG, maybe that could be the place where developer docs go in future? It could act as a landing site for the developer portal as a whole.

1 Like

But please make the website in such a way, that it is easy to post tips, demos and articles easy, like in a blog.

That’s a blog, not a development portal. Let’s not conflate things and derail the discussion, please.

Ideally, the “new infrastructure” would be the same mechanism we use for the continuous integration of our libraries and applications; we use the same mechanism for static web pages, like the new GTK website.

Our main problem is that, while publishing static web sites is easy, publishing API references is hard; we need a way to “push” the built documentation artifacts from multiple projects from the CI runners—which are stateless and pretty much with zero permissions—to a place that can be reached by a web browser. We still haven’t figured out how to do that safely.

Ok sorry :slight_smile:

From a DX perspective, I’d be OK with having a separate site for the API references, if it gets us to a better place overall.

Would it be interesting to have a single static site for the HIG and other hand-written developer docs, and pair that with the API references somehow?

I think so, yes.

It would solve the issue of copying the content from the wiki and publishing it into developer.gnome.org for the “How Do I” pages, for instance.

The current gnome-devel-docs are also kind of hard to update, and it’s hard to see how to change them.

The new GTK website has a nice “documentation” section that is built from static content, and can easily point you to the repository for filing issues or even editing the page on GitLab. I was planning to move a lot of the GTK/GLib wiki content there.

Would it be interesting to have a single static site for the HIG and other hand-written developer docs, and pair that with the API references somehow?

I think so, yes.

Cool. I’ve chatted with the other designers about this. We could potentially start by making a new site that has a simple landing page for the GNOME developer portal, plus the HIG. Once that’s done we could gradually migrate more developer docs over to the new site.

The advantage of that approach: we wouldn’t have to solve all the problems at once. The disadvantage is that we could end up in a perpetual half-finished state…

@ebassi @allanday I think I can help you guys out.

Problem

What I understood so far from the above conversation is that we are looking to create a single, static website, which contains the documentation for various GNOME related projects. Now, what we want to do first is to access the documentation of the individual projects. We can do this through Gitlab API.

Fetching Documentation

We can create a YAML/JSON file in our repository for New HIG website, which will list the project IDs and the documentation folder for project. Once we have this information, we can run a scan procedure on each of the project and check whether new commits have been made since the last scan procedure took place. If there are commits which are related to the project’s documentation, we can download the documentation files recursively on our CI runner. In this way, we don’t need to fetch documentation for each project every time but rather get only those files that changed since the last build of HIG website.

Converting to Static Website

Once we have the documentation, we can build a static website, either using Jekyll or Frozen-Flask. The advantage of Frozen-Flask is it is written in Python. So, if we need to have some logic to build the website, it is the best option. It uses almost same template syntax as used by Jekyll. Another advantage is we can use Python wrapper of Gitlab API. This will keep the CI environment clean. Otherwise, if we go for Jekyll to build the website, we need to have Ruby and Python environment at the same time, which can cause issues.

Example Projects

I designed the new GTK website using Jekyll. I designed GNOME Hackers using Gitlab API and Frozen Flask. Both of these projects use the same fundamentals of generating a static website, only differing on the need of building them on a logic.

I am excited for this project. I personally feel it is one of those things required by GNOME.

3 Likes

Hey @revgeetdhillon! Thanks for the offer! We’d love your help.

I think we have two types of content here:

  1. The hand-written developer docs. This includes the HIG, some other parts of the gnome-devel-docs, and the “How Do I” wiki pages.
  2. The API reference documentation that is generated from all the various platform modules.

I think that all of the first type can live in a single repo and be hosted by a static website.

The second type is trickier. I think that it would be fine to have a second site for that, and integrate the two (perhaps with a shared header or similar).

Does that make sense?

In my opinion, maintaining two codebases is going to be cumbersome, especially when it comes to web. We surely don’t need this kind of workflow. We can easily store the documentation related to HIG, How Do I and gnome-devel-docs in the repository itself and build the API references part of the website using Gitlab API and Gitlab CI by scheduling the CI to run once every day.

I am ready to work on this project but Ima university student, and probably won’t have enough time to work on this without some support. If you guys can get this in Google Summer of Code, I can surely work on this project. Let me know your future plans.

This topic was automatically closed 14 days after the last reply. New replies are no longer allowed.