Knowledge Center Article Writing Guidelines

Tone

Professional yet approachable: Maintain a friendly and professional tone that is easy for users to follow.
Understandable for any user: Avoid overly technical jargon unless necessary, and explain terms when used.
Customer-first language: Speak directly to the user using "you" and "your" to personalize instructions.
Consistency: Standardize terms across all articles. For example: Use "Tracking API" (not “API for tracking”). (see the list of standard terms in this guide)
Actionable instructions: Focus on what users need to do. For example: Instead of “The settings can be accessed,” write “Go to the Settings tab.”

Structure and Formatting

Key Sections to Include

Intro (below main title, before first section): A short summary explaining the purpose of the article and who it’s for.
Sections: Divide each subtopic in a section.
Step-by-Step Instructions: Use numbered lists for clarity / Write each step as a single action to avoid confusion.
FAQs or Troubleshooting: Include a short section addressing common issues.
Conclusion or Next Steps: Suggest what users can do after completing the steps or link to related articles.

Titles

Use Large Title for the main article title (e.g., How to Set Up Your Tracking API).
Use Medium Title for key sections
Use Small Title for subsections

Content Formatting

Short paragraphs: Keep paragraphs concise, ideally 2–3 sentences.
Lists: Use numbered lists for step-by-step instructions and bulleted lists for related points or options.
Sections: Ensure content is clear and visually separated using spacing between sections.

As this tool doesn't provide multi level list, in case needed you will need to mix normal text and integrated list.

Example 1: Bulleted list inside numbered list:
1) Start by checking those stuff
This one
That one

2) Continue like this
Doing this
And doing that

Example 2: Numbered list inside Bulleted list:
- Try those steps
Do this
Do That

Example 3: Numbered list inside Numbered list:
A) This is the first step
This is the first part of the first step
This is the second part of the first step

B) This is the second step
This is the first part of the second step
This is the second part of the second step

Example 4: Bulleted list inside Bulleted list:
- Try any of the following
This
That

Style

Links

Refer to another article: "Check how to this in this article"
Refer to a page: "See all details in Ship24's Public API Documentation"

Screenshots

In order to have a consistent style across all screenshots, please follow these rules:
1) Tool
Use the chrome extension Nimble Capture.
In inspector create / use a custom device of size 1600x900 when taking the screenshot.
Take the screenshot of full page when applicable OR select a specific part when applicable (modal, drop down, etc).
Highlight key areas: Use red rectangles of weight = 3.
If showing steps, add numbers (red).
Texte: Never write on screenshot direclty.
Format: always provide the same screenshot size of Width = 1600px / Height = 900

Example of instruction with screenshot:
In your dashboard, go to "Your Tracking Page".
Select the "Settings tab".
Enter the desired
Click on the tab "Email Layout".
Input the Banner Image by clicking on "Upload your image".

Markup Style

Use a consistent style scheme for annotations:

- Directly on the text:
Bold : For emphasis Ital*
Italic: For examples

- In box:
For Tips: "Add the shipment date to ensure more accuracy"
For Information: "Some courier regularly reuse the tracking numbers, making them non-unique"
For Warning: "Adding the wrong destination country will likely result in our system disregarding the data, hence bringing no result"

Article Length

Keep it concise: Aim for articles to be 500–800 words, with a maximum reading time of 3–5 minutes.
Split long content: For lengthy topics, create multiple articles and link them as related resources.

Updated on: 31/01/2025