IONOS DevOps Central Writing Style Guide

This is a style guide for the IONOS community site tutorials. It covers general article format, Markdown usage, and other standards.

Keeping a consistent format across all articles is important. Not just for a consistent look and feel, but to help new users easily find and understand the information the article is presenting.

Article structure

Article title

Write the article title as if it starts with “How to” but leave off “How to.”

Example: An article about configuring Foo on a Kubernetes cluster should be titled “Configure Foo on a Kubernetes cluster.”

Table of Contents

All articles should start with a Table of Contents. Each item on the Table of Contents is a link to the relevant section.

To create these links, use ## for the header of each section:

## Article Structure

You can then link to this section by putting the title of the article (capitalized) in square brackets, followed by the link to the article (prefaced by a #, all lower-case, with a dash connecting each word and no spaces).

[Article Structure](#article-structure)

Headers

Use two ## for the section header. Use three ### for the sub-section header.

Be sure to also list these sub-sections in the Table of Contents, in a nested UL.

General suggestions

Try to limit articles to a single subject. If you find an article is covering more than one subject, consider splitting it up into more articles and adding links between them.

Screenshots

Screenshots should be no more than 960px wide.

All images (including screenshots) should include alt and title text.
![alt text](/path/to/img.png "title text”)

All images (including screenshots) should have descriptive filenames with dashes instead of underscores.

  • Bad: “image002.jpg”
  • Bad: “setup_screenshot.jpg”
  • Better: “screenshot_of_web_panel_setup_page.jpg”
  • Best: “screenshot-of-web-panel-setup-page.jpg”

What NOT to put in a screenshot

Please do not use screenshots for code samples, configuration file snippets, and other cases where the user will have to type in the text themselves. Put this in a large code block, so that users can copy and paste it into the files.

Markdown usage

Note: This is not intended to be a guide to Markdown code. A few good sources for Markdown syntax (including how to create UL, OL, bold, italics, and more) include:

Code

There are two ways to indicate code: inline and indented blocks.

For inline code, bracket the word or phrase with backticks (`).

In this sentence, the word `IS` will be higlighted as code.

For indented blocks of code or command line sessions, use 4 spaces (not Tab) to indent.

postgres=# \password
                                        Enter new password:
                                        Enter it again:
                                        postgres=# \q
                                        exit

What should be marked as inline code:

  • Commands: “Use ls to list the directories.”
  • The name of a software package or script you will be invoking: “Restart mysql when you are finished.
  • Directories and file paths: “Go to /usr/bin first.”
  • Filenames: “Open config.php and update the username.”
  • File extensions: “Look for a .vmdk file.”

What should not be marked as inline code:

  • Commands that are more than a few words long: Use indented blocks instead.
  • URLs: Make these a clickable link instead.
  • The name of a software package in general usage: “You will need to update MySQL to the latest version.”
  • Something in a screenshot that you want to highlight: Use bold instead.

Example data

Please use the following for example data in your article, in both text and screenshots:

User name: JDoe or jdoe
First name: J
Last name: Doe
Password: thepassword
Address: 123 Main Street, Anytown, USA
URL: www.example.com or http://example.com
IP address: 192.0.2.0
Database name: mydatabase

Misc grammar

“Setup” vs “set up”

  • Use “setup” when it is a noun. For example: “Edit your setup file” or “This is your setup.”

  • Use “set up” when it is a verb. For example: “This is how to set up your server.”

Capitalizaton in titles

Article title

Use standard AP guidelines for capitalizing the title of the article. Capitalize all of the nouns and verbs, but do not capitalize the small connectors.

In other words, capitalize every word with more than 3 letters. Capitalize 1-3 letter words only as necessary.

Words that are NOT capitalized, unless they are the first word of the title: a, an, and, at, but, by, for, in, of, on, or, the, to, and up.

Examples

  • Bad: “How To Secure An SSH Server On Ubuntu”
  • Bad: “How to secure an SSH server on Ubuntu”
  • Good: “How to Secure an SSH Server on Ubuntu”

Section and sub-section titles

Inside the article itself, use “sentence case” for article section titles, and sub-section titles.

  • Capitalize the first word of every title.
  • Do not capitalize any of the other words.
  • But capitalize any proper nouns that would be capitalized anyway (like Linux or CentOS).

Examples

  • Bad: “Edit Your Setup File In CentOS.”
  • Bad: “Edit your Setup File in CentOS.”
  • Good: “Edit your setup file in CentOS.”

Verb tense in titles

Write titles as a command (imperative tense). Do not use the gerund (-ing) form of the verb.

Examples

  • Bad: “Securing the Apache server.”
  • Good: “Secure the Apache server.”

If it helps, imagine that each title begins with “How to” or “Next you must.”