Guidelines for articles
S’abonner

Maxence Perrin

7 septembre 2019 14:49

Here are the guidelines for writing articles in the Mybee Box Help center. You'll find the main structure to follow and the style. You will also find blocks of code for specific formatting elements to boost the readability of your articles.

Article structure

Types of articles

Articles can be divided into two categories :

No scroll articles: These articles are short and fit on a single page on a 13' screen. They can be read in a glimpse of an eye.; They do not require Title structure
Scrollable articles: Scrollable articles are longer articles that will require the user to scroll down to read the whole article.; They require a Title structure

<!-- HTML for horizontal description list -->
<dl class="dl-horizontal">
 <dt>No scroll articles</dt>
 <dd>
 These articles are short and fit on a single page on a 13' screen. They can
 be read in a glimpse of an eye.
 </dd>
 <dd>They do not require Title structure</dd>
 <dt>Scrollable articles</dt>
 <dd>
 The rest of the articles will require a title structure to organize the content.
 In case of a very long article a bullet list of title with direct link must
 be added.
 </dd>
</dl>

<!-- HTML for danger text -->
<span class="text-danger">They do not require Title structure</span>

Manage long articles

In case of a very long article differents solution can be used to reduce the size :

An accordion

To hide part of the content that will be toggle by the user when need

<!-- HTML for accordion -->
<div class="accordion accordion--default">
 <div class="accordion__item">
  <div class="accordion__item-title">
   <strong>Item title 1</strong>
  </div>
  <div class="accordion__item-content">
   <p>Item 1</p>
  </div>
 </div>
 <div class="accordion__item">
  <div class="accordion__item-title">
   <strong>Item title 2</strong>
  </div>
  <div class="accordion__item-content">
   <p>Item 2</p>
  </div>
 </div>
</div>

Breakdown in a prev / next suite of articles

To reduce the content in shorter articles with easy navigation between them

Précédent

Suivant

<!-- HTML for navigation between article -->
<table class="table">
 <tbody>
  <tr>
   <td class="wysiwyg-text-align-left">
    <a class="btn btn--primary" href="/hc/fr/articles/<ARTICLE ID>" target="_self">
     <strong class="wysiwyg-font-size-medium">
      <em class="fas fa-angle-left">&nbsp;</em> Précédent
     </strong>
    </a>
   </td>
   <td class="wysiwyg-text-align-right">
    <a class="btn btn--primary" href="/hc/fr/articles/<ARTICLE ID>" target="_self">
     <strong class="wysiwyg-font-size-medium">
      Suivant <em class="fas fa-angle-right">&nbsp;</em>
     </strong>
    </a>
   </td>
  </tr>
 </tbody>
</table>

A summary bullet list

To present the structure of the articles to the user and link to navigate in the content

Summary

Article structure
Article content
Article elements

<!-- HTML for ordered bullet list -->
<div class="callout callout--transparent">
 <h4 class="callout__title">
  <em class="fas fa-list-alt">&nbsp;</em> Summary
 </h4>
 <ol class="list-colored">
  <li>
   <a href="#h_cfe01e35-157a-468c-b37e-9849e20a4a10" target="_self">Article structure</a>
  </li>
  <li>
   <a href="#h_210fc793-58f7-44b7-a277-2220e4bb8ff6" target="_self">Article content</a>
  </li>
  <li>
   <a href="#h_7ef04195-6b52-43f6-9dff-d0dc6b8ad3bc" target="_self">Article elements</a>
  </li>
 </ol>
</div>

Article content

Style

Article must be addressed to our customer on a friendly ton ("tutoiement" in french) with a wording "from the street" (that can be understand by anybody). Specific terms related to Cashless can be used if they are defined in the Cashless glossary.

Readability

Article readability is the most important factor when it comes to user attention. If an article looks too long, too complex, too boring they will drop it and write an email to customer support. To improve readability you can use formatting elements but not in excess (this article is voluntarily presenting all possibilities and is ~~an example~~).

Attention

Formatting element must be added as HTML in your article. Be careful when you copy and past code as a single missing tag (this is a tag: <p>) can mess up your content. Do not hesitate to preview the article each time you add new code.

Info

Screenshots are very useful to show or explained a "how to" but it has some drawbacks :

it extends a lot the length of an article
it must be updated
it can be misleading when not done correctly (with indication, etc.)

Have a look at the Screenshot section below to improve them.

<!-- HTML code for a warning callout -->
<div class="callout callout--warning">
 <h4 class="callout__title">
  <em class="fas fa-exclamation-circle">&nbsp;</em> Attention
 </h4>
 <p>The callout content</p>
</div>
<!-- HTML code for a info callout -->
<div class="callout callout--info">
 <h4 class="callout__title">
 <em class="fas fa-info-circle">&nbsp;</em> Info
 </h4>
 <p>The callout content</p>
</div>

Process

You must start with the redaction of your article content. No formatting, no complexity. The content itself must be as simple as possible and organized to be easy to follow and understand.

Once the content is set you can use formatting element to emphasize a specific part or in the contrary mitigate another. Use dedicate style for article elements in the next section to match other articles style

Finally, integrate your article in the rest of the knowledge base content with links from other articles, button in the previous article, etc.

<!-- HTML code for tabs -->
<div class="tabs tabs--colored-1">
 <div class="tabs-menu">
 <span class="tabs-link is-active">Tab 1 Title</span>
 <span class="tabs-link">Tab 2 Title</span>
 <span class="tabs-link">Tab 3 Title</span>
 </div>
 <div class="tab">
 <p>Tab 1 content</p>
 </div>
 <div class="tab is-hidden">
 <p>Tab 2 content</p>
 </div>
 <div class="tab is-hidden">
 <p>Tab 3 content</p>
 </div>
</div>

Make it searchable

Your article needs to be found when the user searches for it. To improve searchability here are some points to follow :

A good title: Good title match the user request. It could be a question
Cover one topic: Your article must cover one topic to be relevant in user search results
Introduction keywords: Zendesk weight more heavily the first 75 words of an article than the rest. Use a ot of keywords in your introduction

<!-- HTML code for description list -->
<dl>
 <dt>A good title</dt>
 <dd>Good title match the user request. It could be a question</dd>
 <dt>Cover one topic</dt>
 <dd>
 Your article must cover one topic to be relevant in user search results
 </dd>
 <dt>Introduction keywords</dt>
 <dd>
 Zendesk weight more heavily the first 75 words of an article than the rest.
 Use a ot of keywords in your introduction
 </dd>
</dl>

Article elements

Availability

The availability block must be added at the top of an article to indicates to users with which formula or license the feature is available.

Disponible avec

basic

standard

plus

Disponible avec

basic

standard

plus

Disponible avec

basic

standard

plus

Disponible avec

Espace utilisateur Cashless.fr

Disponible avec

Application Preo

<!-- HTML for availability block -->
<table class="table table-plan">
 <tbody>
  <tr>
   <td>
    <strong class="wysiwyg-font-size-medium"><em class="fas fa-tasks">&nbsp;</em> Disponible avec</strong>
   </td>
   <td class="wysiwyg-text-align-center">
    <span class="wysiwyg-color-black30"><strong><em class="fas fa-check">&nbsp;</em> basic</strong></span>
   </td>
   <td class="wysiwyg-text-align-center">
    <span class="wysiwyg-color-black30"><strong><em class="fas fa-check">&nbsp;</em> standard</strong></span>
   </td>
   <td class="wysiwyg-text-align-center">
    <strong><em class="fas fa-check">&nbsp;</em> plus</strong>
   </td>
  </tr>
 </tbody>
</table>

Menu navigation

The menu navigation block indicates a user where to find in the back office or application the describe features.

Système Cashless > Cashless.fr > Paramètres

<!-- HTML for menu navigation block -->
<div class="callout">
 <p class="callout__title">
  <strong> <em class="fas fa-landmark">&nbsp;</em> Système Cashless &gt; <em class="fas fa-shopping-cart">&nbsp;</em> Cashless.fr &gt; <em class="fas fa-cog">&nbsp;</em> Paramètres</strong>
 </p>
</div>

Screenshot

Video

Vidéo can be embed in the article easily. You only need the video to be uploaded on youtube.

Code

<!-- HTML for video -->
<div class="embed">
 <iframe src="https://www.youtube.com/embed/I3GcYXHlHzo?showinfo=0&amp;rel=0&amp;modestbranding=1" width="640" height="350" frameborder="0" allowfullscreen=""></iframe>
</div>

Logo des applications

SYNC	POS	TPE	OTRA	TPE

<!-- HTML for table -->
<table class="table table--color-header">
 <thead>
  <tr>
   <th class="wysiwyg-text-align-center">SYNC</th>
   <th class="wysiwyg-text-align-center">POS</th>
   <th class="wysiwyg-text-align-center">TPE</th>
   <th class="wysiwyg-text-align-center">OTRA</th>
   <th class="wysiwyg-text-align-center">TPE</th>
  </tr>
 </thead>
 <tbody>
  <tr>
   <td class="wysiwyg-text-align-center">
    <p><img src="/hc/article_attachments/15641763975836" alt="SYNC_512px.png" width="150" height="150"></p>
   </td>
   <td class="wysiwyg-text-align-center">
    <p><img src="/hc/article_attachments/15641801927580" alt="POS_512px.png" width="150" height="150"></p>
   </td>
   <td class="wysiwyg-text-align-center">
    <p><img src="/hc/article_attachments/15641801923228" alt="TPE_512px.png" width="150" height="150"></p>
   </td>
   <td class="wysiwyg-text-align-center">
    <p><img src="/hc/article_attachments/15641801925916" alt="OTRA_512px.png" width="150" height="150"></p>
   </td>
   <td class="wysiwyg-text-align-center">
    <p><img src="/hc/article_attachments/15641801924508" alt="PREO_512px.png" width="150" height="150"></p>
   </td>
  </tr>
 </tbody>
</table>

Boutons

Click me

Start !

Let's Go

<!-- HTML for classic button -->
<a class="btn btn--primary" href="/hc/fr/categories/<ARTICLE ID>" target="_blank" rel="noopener">
 <span class="wysiwyg-font-size-large"> Click me </span>
</a>
<!-- HTML for prepend icon button -->
<a class="btn btn--primary" href="/hc/fr/categories/<ARTICLE ID>" target="_blank" rel="noopener">
 <span class="wysiwyg-font-size-large"><em class="fas fa-rocket">&nbsp;</em> Start ! </span>
</a>
<!-- HTML for append icon button -->
<a class="btn btn--primary" href="/hc/fr/categories/<ARTICLE ID>" target="_blank" rel="noopener">
 <span class="wysiwyg-font-size-large"> Let's Go <em class="fas fa-arrow-alt-circle-right">&nbsp;</em></span>
</a>

Attention

The callout content

Cet article vous a-t-il été utile ?

Utilisateurs qui ont trouvé cela utile : 1 sur 1

Guidelines for articles S’abonner

Summary

Article structure

Types of articles

Manage long articles

Summary

Article content

Style

Readability

Attention

Info

Process

Make it searchable

Article elements

Availability

Menu navigation

Screenshot

Video

Code

Logo des applications

Boutons

Attention

Guidelines for articles
S’abonner