Follow

The purpose of this article to maintain consistency between user manual articles, despite being edited or created by multiple authors. The formatting in this article is meant to emulate a knowledge base article currently in production. 

 

Jump to:

 

  

 

Title

 

When naming a new article, the first word is typically a present participle (ending in -ing) and is capitalized. There are a few circumstances where this isn't the case. The words following are not capitalized unless they are referring to a UI component.

 

There are a few article that need to be in both the Students and Hobbyists section and the Educators and Administrators section. When this is the case, add either (Students & Hobbyists) or (Educators), respectively, to the end of the title. 

 

Examples:

 

  • Exporting Gradebook data for a class
  • Creating a class
  • Resetting your SmartMusic password (Students & Hobbyists)

 

 

Text

 

This article is setup to reflect how the text and images should be placed in a typical article. In most cases, the first thing a user should see is an introductory paragraph explaining the main goal of the article. This paragraph should also contain warnings if there are limitations to the function or destructive aspects to the function. These warnings are in italics.

 

Depending on the article, a Jump to section immediately follows the paragraph. This section links to steps or topics for easy browsing. 

 

Some topics require few steps (ex. Archiving a teacher). Others require detailed steps within general steps (ex. Getting started in the new SmartMusic as an Administrator). If a topic only needs a few steps, these steps can simply be outlined using numerics. If a topic needs steps to be broken down into substeps, use extra large font to indicate the start of a new group of steps or topics (ex. Title, Text, Screenshots, etc. in this article). 

 

There should be a paragraph of space in between most body elements like images. The only time this isn't true is between sections. An extra space is added to separate sections (ex. the space between Arrows and Writing in this article). 

 

 

Writing

 

Consult the MM Technical Communications Style Guide for writing style and appropriate formatting. 

 

 

Buttons

 

If there is a button that the customer will need to click in the UI that isn't text based, use an image of the button, like next_button.png, instead of bolded text. The button images are typically sized 20x20px. Buttons need to be placed inline. Use img class="inline-img"

 

  

Screenshots

 

All of the images within these KB articles are made on a Mac for consistency sake. There were some display issues when taking screenshots on a full screen so now we use a width of 1024px for full screen images. There are circumstances when a width of 1280px can be used (the Practice Analysis page looks too crowded with using 1024px). Screenshots of individual sections, like a deck on the Home page, do not have any size restrictions. 

 

key_drop_down.png

 

 

Arrows

 

Some screenshots require arrows to point out certain UI elements. These arrows are SmartMusic orange (#ec8b30) and are 2px thick when added to a screenshot created on a non-retina screen. Make the lines 4px thick when the screenshot is taken on a retina screen. Always use a 45 degree angle. The legs of the arrow are .236 inches in length. The tail of the arrow can be any size. 

 

 

 

Labels

 

Each article should have labels added to improve search results. Use UI text and keywords that a user might use to search as labels.  

 

labels.png