Skip to main content

Your submission was sent successfully! Close

Thank you for signing up for our newsletter!
In these regular emails you will find the latest updates from Canonical and upcoming events where you can meet our team.Close

Thank you for contacting us. A member of our team will be in touch shortly. Close

  1. Blog
  2. Article

toto
on 11 March 2020


TL:DR The tutorials site was refreshed. Tutorials are written in Discourse. They are then pulled and displayed on different sites: ubuntu.com, snapcraft.io, maas.io and jaas.ai.

Contributing to open source tools goes beyond writing code. Some of the best contributions simply explain to others how to use the software through tutorials and documentation.

To help communities easily create and contribute to tutorials, recent updates have been made, which have been outlined in this article.

What existed

Our tutorials were written in a git repository as markdown files, which were then converted into HTML format when building, and deployed into a nice looking website. 

This was good, but all tutorials were aggregated in the same place and it felt complicated to link it to other sites like snaps, juju or maas.

This process meant that in order to contribute, technical knowledge around using git, making code proposals, etc, was required. 

From a user that just wants to share a few tips, to a technical writer that wants to provide in-depth tricks, tutorials should be written by everyone.

What works for documentation

Discourse is a platform made for community discussions. One of the uses of the platform is documentation management. To make it easier for communities to stay up-to-date, the documentation can be modified by anyone. Once a change is made the site will pick the latest version and display it nicely in its documentation section.

For example, this post on Discourse:

Becomes this page in snapcraft.io’s documentation:

This allows contributors to have much more control over the content and removes the technical overhead of using git, building sites, etc. This makes the documentation easier to manage for the writers and the website developers, since the site gets the latest updates

It seemed quite natural to have the same process for tutorials.

What was updated for tutorials

Most of the tools have Discourse platforms of their own: snap, maas, juju and ubuntu. A new category was added to each of them, the tutorials category, with all of the existing tutorials imported into this new category

In the same way that documentation is generated, a new section on each website has been added. It pulls directly from Discourse to display a web page. You can find this section on ubuntu.com, snapcraft.io, maas.io and jaas.ai.

As an example this Discourse post:

Becomes this page on ubuntu.com tutorials section:

How does it work?

Most of Canonical’s websites are written in Python using the framework Flask. The webteam wrote a Python module that gets the data from the relevant Discourse and gives the right context to the HTML

What is great about it is that from now on when a new tool would require a tutorials section, it becomes very simple to integrate it in the relevant website.

We need you!

At Canonical we love to share what we learn, but we also love to hear stories from the community.

If you have anything that you would like to share as a tutorial, come and meet us in Discourse. All the information about writing tutorials can be found in this great tutorial about How to write a tutorial.

Related posts


Anthony Dillon
25 October 2023

Web team – hack week 2023

Design Article

Today, around 96% of software projects utilize open source in some way. The web team here at Canonical is passionate about Open source. We lead with an open-by-default approach and so almost everything we do and work on can be found publicly on the Canonical Github org. It is not enough to simply open our ...


Goulin Khoge
14 October 2022

Introducing a VSCode extension for Vanilla CSS Framework

Ubuntu Article

The Vanilla CSS Framework is a utility class-based and customizable SASS library that is the go-to when it comes to styling websites and dashboards across the majority of projects at Canonical. Knowing all the class utilities could be tricky. That’s why we make sure that our documentation is up-to-date and accessible as much as possible. ...


toto
4 October 2022

3 step guide to start Hacktoberfest

Ubuntu Article

Last week, the web and design team organised an internal Hacktoberfest. Our goal was simple: contribute to Open Source projects, understand what makes a great contribution experience, and how we could get inspired for our own projects. Here are 3-step guides from our experience during this Hacktoberfest. 1. What should I contribute to? He ...