Writing Style #
Voice & Tone #
When writing for our customers, we focus on making things clear and easy to understand. Our goal is to give them useful information without confusing them. We avoid complicated language and make sure every necessary step is explained.
We write for both technical and non-technical readers, so our articles need to be simple but informative to both types of readers. We do this through great copy and a clear structure.
Humor is welcome, but only if it fits naturally. Most importantly, we want to help our customers without talking down to them or assuming they know everything.
Keep It Simple: Use clear, easy-to-understand language. Avoid long, confusing sentences and complicated words. Use active voice to make the writing direct and easy to read.
Be Respectful: Write in a way that treats the reader as an equal. Don’t assume they know things already. Make sure to provide all the details they need, with links to more info if necessary.
Be Clear and Helpful: Focus on giving useful information instead of long explanations. Guide readers step-by-step, and think about what they might search for so they can find the answers easily.
Use Humor Carefully: Humor is great if it fits naturally, but it should never be forced. If you’re not sure if it works, leave it out. Keep the focus on being helpful and clear.
Our tone is informal with a big focus on clarity. Humor is encouraged but only if it fits the mindset a user has when reading it. Think about why users are here. If a user reads an article explaining how Search works, they are likely in a discovery mindset, and humor can work well.
However, if they are browsing FAQs or troubleshooting articles, they are likely already annoyed by a problem, and simply need a clear solution. Mindset matters ;)
When humor is used, make it nerdy - We love references to Star Wars, Lord of the Rings, The Matrix and other geek-culture phenomenons. It often works very well in code examples, as you will see ;)
Types of articles #
When you are writing, consider which of these types best solve the users need.
Informational #
Explains the concepts of a product or feature. Readers are usually in discovery mode when reading these and want to understand how it works. These articles do not include steps or thorough guidance through the backend, but clearly explains how each part works.
Examples:
How-Tos #
Explains how to achieve a certain outcome. These require step-by-step guidance explaining the exact buttons that users should click and configurations they should go through. Readers are usually trying to achieve something specific when reading these.
Examples:
FAQs / Troubleshooting #
Explains the most likely solutions to common questions or issues. Readers are often frustrated to some degree when browsing these, because something does not work as expected. These should be clearly labeled with the question a reader will have in mind, and provide clear explanations of how to solve it.
These are never individual articles, but are collected under FAQ for a specific product, feature or integration.
Examples:
Title & Description #
The title of your article should always be clear and concise. A good title contains maximum 3 words, and ideally just 1.
A good title is “Omnisearch”. A bad version is “Our Omnisearch Feature”. It adds too many unnecessary words and makes it harder to navigate the menu structure.
Short titles work well because they are easy to browse, and combined with a logical menu-structure, we keep the KC easy to navigate.
Article descriptions should be a single phrase that adds context to the article. It helps readers validate if this article is what they were looking for. Avoid repeating the title in your description - it should complement it.
A good description for Omnisearch is: “A single full-page window that serves your visitors with the results that are most likely to convert”. It clearly elaborates on what Omnisearch is, in a single phrase.
A bad one is: “Omnisearch is a new feature in our search product”. It repeats the name of the feature and its place in our catalogue, which is already clear from the menu of the KC.
Headers #
These are crucial for making articles easy to skim and navigate. Use them to clearly separate different parts.
Headers are hierachical, and are always used in the following order:
- h1: Only used by the title
- h2: Main paragraph
- h3: Subtitle to h2
- h4: Subtitle to h3
We never use smaller headings than h4.
All h2’s and h3’s are used automatically to create the Table of Contents.
Paragraphs #
When writing articles, we want readers to be able to navigate and understand them easily. After all, they will rarely read the full article, but skim through it to find the parts they need.
The ideal paragraph is between 1-3 lines. Longer paragraphs quickly end up looking like walls of text. When you write, make sure that its easily skimmable by adding line breaks after at least every 3rd line (when viewed on a 13 inch laptop).
This is not strict requirement but a good rule of thumb. Our brains tend to look at large blocks of text and deduce that they are hard to read, even if they aren’t.
To visualise the difference it makes, check the section below, where the line breaks have been removed. Harder to skim, right?
When writing articles, we want readers to be able to navigate and understand them easily. After all, they will rarely read the full article, but skim through it to find the parts they need. The ideal paragraph is between 1-3 lines. Longer paragraphs quickly end up looking like walls of text. When you write, make sure that its easily skimmable by adding line breaks after at least every 3rd line (when viewed on a 13 inch laptop). This is not strict requirement but a good rule of thumb. Our brains tend to look at large blocks of text and deduce that they are hard to read, even if they aren’t. To visualise the difference it makes, check the section above, where the line breaks are added. Easier to read, right?
Links #
Whenever it makes sense, include links to other parts of the KC. Keep in mind that the user should have everything they need on any 1 article, so its often worth at least summarising the points, before linking to another article with more info.
Example:
Before you continue, make sure to create a new Content block. You can do this from Recommendations > Content > Create New . Read more about Content here.
Screenshots #
We use Brandbird for creating slick screenshots. Always include a good contrast background for your screenshot, that does not steal attention, but complements it.
Images are important for adding context to articles and we use them often. However, they should also not make it harder to skim and understand the article. The copywriting comes first.
A good rule of thumb is to include around the same number of images as h2 and h3 headlines More than that, and you are likely over-relying on images.
Images should generally cover the full extent of a page to give the right context.
E.g. instead of showing 3 different images for HTML, CSS and Sub-Designs separately, a single one showing it all in the starting paragraph is better. Annotations are also welcome to help clarify parts of an image.
Videos #
We use Loom or Tella for recording videos. Use their respective Embed features and remember to always choose the Responsive version. They can be added directly to an article like this:
Videos are great for clearly showing all aspects of a feature or how to do something specific. They complement guides well, as readers can often start by watching the video, before using the article for reference.
Videos should never replace written text though, so anything shown in a video should also be written in text.
When recording videos, go through the points chronologically in the same order you wrote the article in, so they are easy to follow.
Menu Items #
We organize the KC logically, and generally in the same order that features are shown in our backend.
Only articles that are applicable to all customers should have their own pages. Any edge-cases should be added under FAQs for the relevant aspect.
Examples:
- Articles explaining how Omnisearch works is applicable to all customers using the product, so it has its own article.
- Debugging why tracked orders are not shown in the dashboard is an edge-case, and is put in the FAQ for Any (Webshop)
Hugo #
Theme #
Our entire KC is written using Hugo Themes - A lightweight templating system that generates static HTML files from Markdown. It allows us to work entirely in the /content folder and Hugo renders it all beautifully through our theme.
Check how to get started with Hugo in the README.md file found in the root folder.
Folders & files #
You work in the content/en folder and in the integrations & platform subfolders.
Translations are handled by Localazy as you can see from the README.md file in the root folder.
The filetree closely resembles the menu structure, because Hugo renders the menu based on the folder structure you see below.
Each article is in its own folder with an _index.md file that you edit. The underscore must be included for Hugo to understand that this is a landing page.
By standard, the title of an article is defined by the folder name, so choose it carefully and follow the existing examples. The title can be overwritten in the front matter of each article.
root/
├── archetypes/
├── assets/
├── content/
│ └── en
│ └── integrations
│ └── act-on
│ └── email-recs
│ ├── _index.md
│ ├── screenshot_10535...
│ └── platform
│ └── search (the search page file)
│ └── writing (this article)
├── data/
├── i18n/
├── layouts/
├── static/
├── themes/
└── hugo.toml <-- site configuration
The URL for each article is generated based on the folder structure down to the last layer, where the _index.md file is. The URL for the above example is /integrations/act-on/email-recs
Front Matter #
This is meta-data you can add to articles, like titles, descriptions, aliases (redirects), categories and more.
Front matter is always located in the top of an article:
---
title: "The Holy Grail"
description: "Monty Python's best movie"
weight: 3
aliases:
- /old/path/to/holy-grail
- /really/old/path/to/holy-grail
---
What is the airspeed velocity of an unladen swallow?...
The most important front matter is:
- title: A custom title for the article. If this is not included, the titlecased folder name will be used.
- description: Shown just below the title on the article page. This is required as it gives valuable context to the reader.
- weight: The articles position in the menu. The lower the number, the higher in the menu it is shown.
- aliases: Old URLs where this article has been located before. Hugo uses this to redirect to this page to avoid 404 errors. If you ever change the folder-name of an article, you will have to add its previous URL as an alias here. But in general, don’t change the folder names. Use title instead.
Writing Markdown #
Markdown is a great markup language that allows you to focus entirely on the content, rather than also struggling with HTML and CSS.
Markdown files are translated to HTML which is then shown to the customer.
It’s super intuitive to use. If you ever need a cheat sheet, check out [the official site](https://www.markdownguide.org/cheat-sheet/.
Below are the most common syntax rules you need.
Headers #
Can be added using a number of # followed by the header text.
The number of hashtags decides the header:
h2: ## Shortcodes
h3: ### Their syntaxes
h4: #### A specific syntax
Paragraphs #
Any text on the same or the following line is displayed as a single paragraph. Adding 1 line of space between lines separates paragraphs:
All text here is one paragraph.
Even the text here will be on the same line as the one above.
Text displayed here gets its own paragraph.
Links & Anchors #
Can be added by simply highlighting the text you want to create a link for, and wrapping it in braces followed by a paranthesis with the link
... read more about [Content here](/platform/content/settings/)
When referencing articles in the KC, you only need to include the relative path like in the example. For external references, include the full URL.
You can use anchors to send readers to specific parts of longer articles, using # followed by a headers ID in the reference.
The ID is a santisied version of the name. E.g. the header “For Developers” will get the ID for-developers.
This can be used to reference headers in within the article itself, or to reference other articles by also including their relative path:
Check the [For Developers](#for-developers) section further down.
Check [Common sync errors for Magento2 here](/integrations/magento-2/faq/#common-sync-issues).
Images #
We use a customised shortcode for showing screenshots in articles.
You should always output images as .webp from Brandbird to keep the quality high and the filesize low.
Images are saved in the same folder where your _index.md is to keep them organized with the article.
The shortcode syntax is:
{{< image "IMAGE_ALT" "FILENAME.webp" >}}
Always write an alt text for the image, so search engines can understand what is shown on them.
UI references #
These are always written in bold with arrows indicating the path to go through.
The KC is translated automatically, so to avoid translating menu items, we use a specific shortcode for referencing our user interface.
The syntax is:
{{< uiref "Search > Designs > New Design > Omnisearch" >}}
The output of this will show as bold text that stays the same across translations: Search > Designs > New Design > Omnisearch
Code blocks #
These come in two variations - inline and block.
An inline code block which is created using two backticks `like this`.
Full code blocks are created by wrapping the code with 3 backticks at the start and end, and adding the code language for syntax:
console.log("What an awesome code example!");
Start writing #
Now you are ready to start writing world class content!
There’s a lot to digest in this article, and you likely won’t remember half of it tomorrow. Take a break, eat something, and read it again.
Then write an article explaining something you care about, to practice your skills. Keep this guide open when you write, so you can reference it. At some point, writing like this becomes second nature ;)
Happy writing!