In this tutorial, you will learn how to write content for tutorials.ubuntu.com and reach a wide audience of both beginner Linux users and advanced users such as developers and system administrators.

We will start by looking at general guidelines, the structure of a tutorial and go through the publication and review process.

What you'll learn

• How to create and structure a tutorial from a single Markdown file
• How to use the additional Markdown features specific to the engine
• How to render it locally to see what your readers will see
• How to get it ready for review by the Ubuntu Docs team

What you'll need

• A computer running Ubuntu 16.04 or above
• The git command-line client (that you can install by running sudo apt install git)
• Docker to run the website locally
• A GitHub account, for the publication and review process

Depending on the topic and your level of experience, writing a tutorial can be a very easy task, but following these guidelines is important to keep the whole set of published tutorials consistent. Let's get started!

Mission of tutorials

Tutorials are step by step guides aimed at a very diverse audience. To provide a good learning experience, a consistent and didactic approach is key.

A good tutorial should:

• be focused on one topic or a very small group of related topics. Keep it simple and on point as people who want to learn multiple subjects will take multiple tutorials.
• produce a tangible result. The topic is demonstrated with a small practical project and not only a theoretical or "hello world" example. The tutorial reader will come out of it with a working example on their environment.
• be short. An estimated 60 minutes for a tutorial is an absolute maximum. Most tutorials should be in the range of 15 - 30 minutes.
• be divided in short steps. Each step is practical and results in user-visible progress.

Tone

The tone of your tutorial should be friendly. Try to make the reader feel that they're building and learning something together with you.

All tutorials should have the same tone, regardless of the topic. This is why you should complete one or two of the existing tutorials before writing your first one.

In short, this isn't a teacher/student paradigm, but rather friends sharing some time together. Thus, "we" should be used as much as possible, like "we have just seen", "we now understand that...". However, "you" can be used for demonstrating things in the user's context, like: "edit your file", "your directory should look like this", "on your system",etc.

And now, let's see the first required step!

Each tutorial is built using a single Markdown file.

This file starts with a set of metadata in Front matter format to be consumed by the tutorials engine. For example, at the top of the source file of this guidelines tutorial, you will find:

Let's have a look at each field:

• id: the identifier of the tutorial to be used in the URL. Keep it short but clear.
• summary: a description of the tutorial (10 to 30 words) to be displayed on the frontpage of the site
• categories: any of cloud, community, containers, desktop, iot, packaging or server
• tags: a comma-separated list of tags used by the site search
• difficulty: the scale spans from 1 to 5. Beginners without previous knowledge of the given topic should be able to follow and understand tutorials from level 1 without any other prerequisite knowledge.
• status: draft or published
• image (optional): an absolute link to an image that will be used when sharing the tutorial on social networks. Preferred dimensions: width should be over 1000px with a 16:9 or 16:10 ratio.
• feedback_url: where to report bugs and give feedback about this tutorial. Unless you have very specific requirements, this should be: https://github.com/canonical-websites/tutorials.ubuntu.com/issues.
• author: the name and email address between brackets of the author of the tutorial. If you don't intend to maintain this tutorial after publication, please use Canonical Web Team
• published: a date in YYYY-MM-DD format, to be updated after any major change to the tutorial

After this metadata section, the tutorial starts.

First impressions matter and the first page of your tutorial should be welcoming and informative. On tutorials.ubuntu.com, an "Overview" page should be the first step of every tutorial.

The overview contains at least three small parts:

• a summary
• a "What you'll learn" section
• a "What you'll need" section.

The summary

The first paragraph or parapgraphs of the overview is a summary of the tutorial's objectives, its purpose and why the reader should go through it. An image can be included, as well as external links.

Example

The "What you'll learn" section

This section includes the list of topics covered by your tutorial. It's a way to align readers expectations with the content they are going to read. Topics are presented as bullet points.

Example

The "What you'll need" section

This is the list of prerequisites the reader needs to meet before starting the tutorial. If there is a need for specific hardware, software or user accounts, this is the right place to talk about it. If there is a need for specific technical knowledge to go through your tutorial, use this section as an opportunity to link to documentation and other tutorials.

Example

Optionally: a survey widget

You can gather some insights on who your readers are by adding a survey widget. Using this widget is not a requirement, but it helps gathering audience statistics and can help making tutorials better as a whole.

To create this widget, you need to use the following syntax:

Note that Google Analytics is used as the survey backend.

When you are done with your friendly and informative introduction, you can start adding more steps (remember, second level titles are used to declare the start of a step) and build your tutorial story.

To do so, we will now go through some content recommendations.

In addition to the previous advice on what a tutorial should be and what is mandatory, you should pay special attention to the following points:

Each step should be concise, but not too short

Be wary of a step's length. In average, 5 to 10 minutes is more than enough for a single step to complete. Don't make them too short either. Naturally, some steps will be shorter than others (such as the first and last steps).

If too long, prefer dividing the tutorial

Tutorials are self-sufficient, but they can nonetheless build upon each other (you can link from the requirements section of the first step, for example). One tutorial could require another tutorial to be completed first. And if you are reusing the same code, ensure you provide a repository as a starting point.

If a tutorial is too long, consider breaking it up into several pieces. However, ensure all tutorials present a distinct objective.

Don't have too many steps

Steps should be concise and tutorials should be rather short. Consequently, you shouldn't have too many steps in your tutorial. We don't want to make the reader desperate by glancing at the number of remaining steps before tutorial completion.

Each step should be rewarding

As a writer, you should try to keep the reader entertained at each step and this is achieved by careful story building. Each step should end on concrete progress towards the end goal. It should be, if possible, tangible and interactive, so that the reader can be familiarised with notions introduced by the step.

To earn bonus reader commitment points, finish a step on a "cliffhanger"!

External links in tutorials

Links to external website are forbidden during a tutorial. We don't want people's attention diverted from the task they are going through (which emphasize the fact that each step should have enough knowledge to be self-sufficient). In particular, do not link the reader to the reference documentation. We want to keep the user's attention on the current task only. Download links are allowed though.

Provide regular code "checkpoints"

This is mostly for developer oriented tutorials, but if this rule can be applied to an admin/advanced users oriented one, please do so!

The advice is to provide regular checkpoints where people can sync back their source code with the tutorial, in particular, at the start of a given step. Readers could have stopped then resumed going through a tutorial, and may not have the source code from previous steps anymore. Consequently, in the case of a code-writing tutorial, please try to provide a link to the current state of the code at the start of a step.

Do not repeat the setup/install phase for each tutorial

Avoid repetitive setups or installation phases, particularly if the tutorial isn't a beginner one. Beginner tutorials should contain a setup phase while more advanced tutorials should reference other beginner tutorials as prerequisites.

On the last page of a tutorial, the project is finished and you remind readers they have reached their goal and have grown some new skills.

Take one or two paragraphs to remind them of what they went through and what they have achieved. That way, readers can reflect upon the various steps and their newly acquired knowledge. Ensure you use a friendly title for this final step.

For example, as a reader of this tutorial, you should have understood what's needed to create a successful learning experience, what the recommendations are, and how the Markdown syntax works. You now know how to deploy the website locally and how to propose your content for review!

On the last page, make sure you also include at least one of the following sections:

• Next steps
• Further reading

"Next steps"

"Further reading"

With another list of bullet points, provide a list of external resources to get more information on the topic. You can link to documentation, related source code, or blog posts that will provide more insights.

The syntax used is by and large regular Markdown syntax, but there are some specificities:

Line breaks and empty lines

• Paragraphs are delimited by empty lines
• Line breaks will create a new line

In the context of an admonition or a survey widget, using an empty line will close it and go back to text.

Images

Images can be hosted locally (relatively linked to the markdown source) or remotely. The tutorial engine will fetch remote images and cache them locally.

When writing a tutorial, it's extremely useful to see how it will render on the website.

We are going to need a local instance of tutorials.ubuntu.com, which is something we can achieve without any advanced technical knowledge: it takes 5 minutes and a single command handles all the process.

To do so, start by cloning the tutorials git repository:

Then enter the tutorials.ubuntu.com directory and launch the run script.

If you have Docker correctly installed, it will build a local tutorials.ubuntu.com instance. The first time (and only the first time) you run this command, it will download all the required dependencies. When the site is ready, a local server starts serving it at http://localhost:8016.

Each time you save a file you are working on, it triggers a page refresh on this local server, allowing for rapid iterations on the content.

Once you can have seen your tutorial in its final form, it's time to share it with the world.

The tutorials repository is managed by the Ubuntu Web and Doc teams. A review process is in place to ensure new tutorials are being looked at by writers, engineers and documentation experts.

Source code structure

The tutorials.ubuntu.com source code contains a tutorials directory. Each of its subdirectories matches a tutorial category: cloud, server, packaging, etc. Your tutorial should be included into one of these.

For example:

Once your tutorial is in the right directory, you can then propose a pull request of your changes.

Congrats, you made it! If you have been watching closely, you are now fully equipped to write a compelling tutorial and take your future readers to new heights!

Now you know how to:

• Create a welcoming and informative intro to your content
• Provide an interesting and easy-to-follow learning experience
• Structure your markdown source file
• Render tutorials locally and submit them for publication

There are a lot of topics to write about and if you are looking for ideas, just think about what you master and frequently do on Ubuntu, something that's useful to you, even if it's an arcane topic or a very simple set of tips you think people would benefit from.

Next steps

• Write your first tutorial on your topic of choice and propose it for publication!
• Pick one of our opened "Content" issues and make your first contribution to the project
• Join the #ubuntu-doc channel on Freenode IRC to chat with the doc team and share your thoughts
• Read other tutorials and help us improving them by opening new issues on GitHub