Snel.com’s Writing Guidelines
We want to make sure that all of our knowledge base articles have a consistent style and quality. Hence, we have developed the following guideline. This guideline will explain which structure, style and tone of voice you should use for your article.
All of our knowledge base articles are to be written in English.
There are three sections in this guide:
The knowledge base articles should be written for all experience levels. This means that the text should contain detailed information without assuming that the reader already knows the topic or that he has a wide technical knowledge. It is important that you include every command from the first SSH connection to the final working setup.
Make sure that you explain why the reader needs to execute a command or why he needs to adjust the configuration or file. The commands need to be logical and the steps should be completely clear. Make sure that you execute the commands of your tutorials on a new server, it is important that the commands work from scratch.
The commands should be correct from start to finish. The reader should be able to have a working installation or usable environment after reading your tutorial.
Friendly but formal
It is important that your tutorial is written reader-friendly and the tone should be formal. Make sure that you use the first person plural (We will start with..) or second person (You need to configure…) etc.
All of our tutorials should have a consistent structure. Make sure that you use the following section in your articles:
- Introduction / What is the goal of the tutorial? Why should the reader follow this tutorial, what are the benefits?
- Step 1 — Explain the first step
- Step 2 — Explain the second step
- Step n — Explain
Title and Goal
When you choose a title for your article make sure that your title is related to the goal of the tutorial. The reader should conclude what you are going to tell when reading the title.
For example, if your tutorial is about installing an SSL certificate your goal is likely to secure a safe connection. A title that includes the goal such as “How to secure your server with Let’s Encrypt SSL” says so much more to the reader.
The purpose of the prerequisites is to explain what information the reader should have before they follow the tutorial. You should provide the reader a bulleted list with all the necessary things to check.
These bullet points may include:
- The necessary things required for the initial server setup or installation
- Software installations and configurations.
- Required SSL certificates and so on.
Test your tutorial and make sure that your prerequisites are correct. If you have changed a bullet point from the prerequisites make sure that you note that.
In this section, you need to describe what the reader should do. You should describe what the step covers and why the reader needs to execute this step to achieve the overall goal of the tutorial.
You should explain what the reader has achieved by following your tutorial. You should also explain what other steps the reader can execute and refer to other related knowledge base articles of Snel.com.
Make sure that you use code blocks for the following:
- Terminal output
- Dialogues that are in textUse a separate code block for each command that the reader needs to perform.
Use bold text for:
- Hostnames, usernames
- GUI text
- Term lists
- Steps that need to be emphasized in your article
Inline code blocks
Use inline code blocks for:
- Example URLs
- Package names
- File names and paths
- Port names
- Key presses which should be in all in caps, for example, ENTER or DELETE
Please make sure you follow the guidelines below when you add images for your tutorial:
- Use .png file format
- Host images on imgur
- The images should have consistent width and height, the size should not be bigger than 600px.
Make sure that you do not use screenshot images of codes and output. Use screenshots of GUIs or images of server setups.
How can I apply for the Tutorial Program?
Click here to apply for our Technical Tutorial Program.