Editorial Guidelines: Writing for 1&1 Community

Our content aims to inspire our readers and to help them reach their goals. For this reason, the 1&1 Community combines informative articles and tutorials.

We are convinced that great ideas, strategies and specific solutions need to be provided in one central place: the 1&1 Community.

To create high-quality and diverse ideas and tutorials for our readers, we work according to the guidelines below:

Who are we writing for?

On a very basic level, we are writing to make our readers successful and enjoy what they are doing.

This means that our content needs to provide maximum benefit for our readers. It has to inform them the best possible way or guide them towards their goals as easily, clearly and directly as possible.

  • We guide our readers through the topics step by step. We write our texts for experienced readers, not for experts.
  • We test our solutions and make sure they work for our readers.

Here is an example of a clear text providing reasonable instructions for the reader:


Creating a Project with the Symfony Framework

To start a project, you need to download the symfony.phar file. For Linux users, the following commands are needed:

$ curl -LsS http://symfony.com/installer > symfony.phar
$ sudo mv symfony.phar /usr/local/bin/symfony
$ chmod a+x /usr/local/bin/symphony

Another example: Describe the status and separate the necessary steps from the optional ones:


The system now sets up your WordPress installation and informs you about the current status. The installation usually only takes a couple of seconds.

Manage your new WordPress website in the 1&1 App Center:

  • If you want to get started right away, click Edit website. Use the username (administrator’s login) and the password you have just created to log in to the WordPress admin area.

The 1&1 App Center provides the options to change the domain of your website or switch to Free Mode.


These examples provide the user with a clear goal and all information required to reach this goal. The second example gives the reader additional information presenting further options. What’s important here: What is essential for the reader always comes first.

Content and structure

We show you how to set up and develop your content to tell your reader an informative, exciting and useful story.

Your content has to be self-contained. This means that every article describes a story or a solution thoroughly form start to finish with as much detail as possible.

If an article requires background information that you cannot integrate into the piece you are currently working on, create another article containing this background information first. This is especially useful in cases when this article can be used as a source of information for other articles as well.

For example, if your tutorial contains the step “Upload data via SFTP”, this is a good moment to create an article for this subtask.

A good article leads to:

  • A well-informed, entertained and motivated reader.
  • A reader who knows exactly where he is and how he can proceed.
  • In the case of tutorials: A successful installation/adjustment/optimization/a solved problem…

This is how we structure our articles:

Introduction/ Teaser

  • Summarize what the article is about and which tools and methods are used.
  • State reasons why this article is useful for your reader.
  • Define the goal: What has the reader achieved at the end of this tutorial.

Here is an example of a motivating and concise teaser:

mod_deflate allows HTML and CSS files to be compressed and reduces the size of transferred files by up to 70%. This results in shorter loading times for your website.

Requirements

Use body text or – which is even better – a check list to state the requirements. Typically, requirements are something like this:

  • Tutorials with basic knowledge. For example: “Adjusting DNS Settings” or “Uploading Data via SFTP”
  • A certain contract type/feature
  • User or access rights
  • Internal and external tools

Example:

This is what you need to activate mod_deflate:

  • A performance server
  • Access to .htcaccess in the root directory via SFTP
  • An FTP client such as FileZilla (download)
  • A text editor such as Notepad++ (download)

If specific tools are needed, always provide a verified download link.

Instructions

Use a specific example to guide your reader through a tutorial. At the end of the tutorial, your reader should have went through this example on his own. If possible, choose examples that your reader can build up on.

Use the active voice for all steps and integrate relevant examples. You reader has to take action to be successful.

Step:

Positive (active, the reader has to act): Paste this code at the end of the .htcaccess file.

Negative (passive): This code has to be pasted at the end of the .htcaccess file.

Example:

AddOutputFilterByType DEFLATE text/html text/plain text/xml text/x-js text/javascript text/css

AddOutputFilterByType DEFLATE application/xml application/xhtml+xml application/x-javascript application/javascript application/json

Interim result

Make sure that your reader never feels unsuccessful and worried after reading 5000 words!

If your reader tackles a longer tutorial, support him with interim results after important subtasks. This will help him to check his success so far and will motivate him to proceed.

Example: This interim result summarizes what your reader has achieved and the information he needs for the next steps:

You have now successfully completed the MySQL database setup. All information about your database is available in the database overview. Please make sure to write down the following information for later use:

  • Database name
  • Databse user
  • Password

Result/Conclusion

Briefly state what your reader has achieved and show him what he can do next.

Style: The most important rules for your articles

Use neutral and informative language. Avoid evaluative and subjective statements such as: old, outdated, problematic, error-prone…
Positive: PHP version 4.1 is no longer supported
Negative: The old PHP version is no longer supported.

Write informative and concise.
Positive: More information on the Load Balancer topic is available under Cloud Server > Load Balancer.
Negative: More information is available here.

Titles and headings

For tutorials, use the gerund in headings and title case. In contrast to the imperative which is making a demand of the reader, the gerund is suggestive and less “bossy”.

Use title case (titles only) – (capitalize: first and last word, all nouns, verbs, adjectives, adverbs, pronouns/do NOT capitalize: prepositions, conjunctions, articles)
Positive: Uploading and Installing Themes
Negative: Upload and install themes

For informative articles, keep the heading short and precise.

Use title case (titles only) – (capitalize: first and last word, all nouns, verbs, adjectives, adverbs, pronouns/do NOT capitalize: prepositions, conjunctions, articles)
Positive: New PHP Versions Available – PHP 5.6.6, PHP 5.5.22 and PHP 5.4.38
Negative: Some new PHP versions have been released

Consider your audience

Write your text in a way that it is easy to understand for your target group.

  • Consider the target group’s preknowledge. This might be, for example: Knowledge of working with computers and the Internet or specific specialized knowledge.
  • Consider the target group’s language skills. Avoid foreign words and specialized terms that your target group may not understand.
  • Use examples that are relevant for the target group.
  • Consider the target group’s expectations, interests and needs in terms of the product or the instructions.
  • Also consider the target group’s concerns in terms of the product or the instructions.
  • Consider other aspects such as age, reading habits or cultural factors.

Voice and tonality

Address your reader personally in your texts. This helps the reader to understand that he is required to do something.

Use the active voice and the present tense.
Positive (active, the reader has to act): Paste this code at the end of the .htcaccess file.
Negative (passive): This code has to be pasted at the end of the .htcaccess file.

Length and structure

Keep it short or in other words: Make it as long as necessary, but as short as possible.
Title, positive: Cancelling the Installation
Title, negative: Cancelling the Previously Started Installation Process

Positive examples for sentence length:

  • Delete unused data to free up storage space.
  • This picture shows the architecture consisting of a network of 100 high-performance servers.
  • Depending on your settings, the data will be displayed as a table.

Clearly separate the individual steps.
Positive:

  • In the menu, select Settings > Basic Settings
  • Click the Applications section.
  • Set up the new application now.

Negative:

  • In the menu, select Settings > Basic Settings, click the Applications section and set up the new application.

Screenshots/Images

If your article refers to a graphical user interface, provide screenshots. Use screenshots to give your reader an overview and to make the steps more transparent. A good screenshot only shows the relevant GUI and highlights important controls.

  • To highlight controls, use frames with 3px and #F8C901.

If you refer to controls in the text, highlight them in bold.

  • Select the desired domain in the Domain Overview.

In the case of cascading menus:

  • Go to Domain Settings > Advanced > DNS.

Mention the GUI label name before the element type.
Positive: Click the Save button in the Settings section.
Negative: Click the button Save in the section Settings.

The height of your screenshots heavily influences the readability of your article. Therefore, use screenshots that are small in height if possible.

If possible, use a consistent aspect ratio:

  • Positive: 16:9 or wider
  • Negative: 4:3

Use the .PNG format, do not use .JPG.

Please rate this post :

Leave a Reply

Your email address will not be published. Required fields are marked *