Write for Snel.com – Writing Guidelines

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 writing guidelines. This guidelines will explain which structure, style and tone of voice you should use for your article.

There are three sections in this guide:

• Style
• Structure
• Formatting

Style:

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.

Technically correct

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.

Structure

All of our tutorials must have a consistent structure and hierarchy must consist of at least 300 words. Since the name of the article in our CSS is already marked as H1, use the following formatting in the body of your articles:

• H2 - Title- max. 70 characters

• Txt – Introduction — What is the goal of the tutorial? Why should the reader follow this tutorial, what are the benefits?

• H3 - Prerequisites - max. 70 characrters —

  • Txt – What is needed to be able to follow this tutorial.

• H4 - Step 1 —

  • Txt- Explain the first step

• H4 - Step 2 —

  • Txt – Explain the second step
    …

• H4 - Step n —

  • Explain

• H3 - Conclusion —

  • Txt – form conclusion

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.

Prerequisites

The purpose of the prerequisites is to explain what information the reader should have before they follow this writing guidelines 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.

Steps

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.

Conclusion

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.

Code Blocks

Make sure that you use code blocks for the following:

• Commands
• Terminal output
• Scripts
• Dialogues that are in textUse a separate code block for each command that the reader needs to perform.

This is how you format these blocks <code class=”EnlighterJSRAW” data-enlighter-language=”generic”>The text will be here</code>

Formatting

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

Images

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.

Linking

We only link externally with a “Nofollow” tag. Always try to add internal links (especially to our product pages) to your article. When you do so, it’s preferable to link above the fold (first or second paragraph).