Documentation Style Guide

Style Guide Reference

This document describes the general style guide for KB articles, and is presented as a general reference example. Each KB article should have a descriptive title that conveys to the user the content of the article. Each KB article should also include an introductory paragraph (like this one) that briefly summarizes the content included in the KB article. (Paragraph / 12pt)

ABOUT THE STYLE GUIDE (Heading 2/Caps/18pt)

When creating a new KB article, the style of the text should be brief and conversational, conveying only as much information as required to assist the user in understanding the feature or issue. If a KB article has different sections, each section should start with a headline as indicated above using Heading 2 in all caps. The body of the KB article will be in the Paragraph format, which should default to 12pt.

ELEMENT STYLES (Heading 2/Caps/18pt)

This section lists each of the possible element references that may be encountered within a KB article, and provides details about how to style them.

Dialogs and Menus (Heading 3 / 14pt)

This section describes the proper styling for Buttons, and other UI elements that we may reference in KB articles. Each particular element is described below.

Dialog Items [Bold Face] (Heading 4/ 12pt)

A dialog item is any item that interacts with the user on a dialog or panel window. Such items include the following:

  • Buttons
  • Dropdown/Popup Menu Names
  • Checkboxes
  • Edit Text items (Paragraph w/ Bullet List Attribute)

Such items should be represented by the name that appears in the UI element, and should be styled using the paragraph style in a bold face. Examples would include the OK button, Cancel button, and Continue button.

Menus [Bold/Italic] (Heading 4/ 12pt)

For menu selection specifications, please specify the full or partial menu path separated by ‘>’ characters. The entire menu path should also be in Bold/Italic. As an example: Main Menu > Sub-Menu > Item.

Text, Filenames & Feature Names (Heading 3 / 14pt)

This section describes the proper styling for literal or example text, file names and paths, URL’s, and feature names. Each particular element is described below.

Feature Names [Bold/Italic] (Heading 4/ 12pt)

When referencing the name of a Feature for the first time, such as Cut & StackPPML Driver, Variable Link Report, etc. these will be presented initially in Bold/Italic. Subsequent references within the KB article can be left in plain mixed case to avoid unnecessary styling within a paragraph.

Product Names [Bold] (Heading 4/ 12pt)

When referencing the name of a Product for the first time, such as CopyFit Module, Bar Code Module, etc. these will be presented initially in Bold. Subsequent references within the KB article can be left in plain mixed case to avoid unnecessary styling within a paragraph.

Literal Text [Quoted & Blue] (Heading 4/ 12pt)

For any literal text that you might type into a user interface prompt, those will always be quoted and colored using the Dark Blue color. As an example: Please enter the text “Hello World, my name is John” and click the Continue button.

File Names, Full Paths, URL’s [Blue] (Heading 4/ 12pt)

For any file names or full paths like C:\Adobe\Adobe Indesign\ or Macintosh HD:Test:Testfile.csv, we just color those Dark Blue. If the filename or path appears on a line by itself, we color those blue as well. For example:

C:\Adobe\Adobe Indesign\   (Paragraph / Blue)

Macintosh HD:Test:Testfile.csv

Alternatively, you may wish to insert these using the Insert > Code Sample method, so they are more set off, as shown below:

C:\Adobe\Adobe Indesign\ 

Macintosh HD:Test:Testfile.csv and this line can get pretty long and it should show a scroll bar now...

Sample Text and Coding Examples (Heading 4/ 12pt)

If we have any sample data, scripting code, or possibly literal text set off by itself, then we use the Insert > Code Sample… feature to create a block, as shown below:

Address,City,State,Zip
Josephine Darakjy,4 B Blue Ridge Blvd,Brighton,MI,48116
Art Venere,8 W Cerritos Ave #54,Bridgeport,NJ,18014
Lenna Paprocki,1210 DJT Boulevard,Anchorage,AK,99501

(Insert > Code Sample)

STEP BY STEP (Heading 2/Caps/18pt)

This section lists example styling for step-by-step instructions. The general way to approach this will be as follows:

  1. Enter step summary (Bold)
    Optionally, use shift-return to place a longer general description on a line by itself in plain typeface, as shown in this example. The step summary should be in bold face. Keep an extra shift-space between steps, as shown below.
  2. Next, enter another step
    Now you just repeat the process for every step that you wish to enter. If you want to have a list of items underneath a step, then you do it like this:

            Here is item 1 (use 8 spaces to indent with preceding shift-return)
            Here is item 2
            Here is item 3

  3. Finally, apply the Numbered List style
    Select all of the steps, and apply the Numbered List style from the icon toolbar. Make adjustments as necessary.

Now here is a list of the same steps but only as single line.

  1. First, you do this
  2. Second, you do this
  3. And third, you do this

IMPORTANT NOTES

In order to set off important notes, please use the Format > Formats > Blocks > Block Quote feature, as shown below:

This would be an important note, something identifying useful information or a helpful tip for the reader of the KB article. This would be an important note, something identifying useful information or a helpful tip for the reader of the KB article. This would be an important note, something identifying useful information or a helpful tip for the reader of the KB article.

SCREEN SHOTS & MOVIES 

This section describes how to position screen shots and embedded movies. 

Screen Shots (Heading 3/ 14pt)

FOR DOCUMENTATION:

All screen shots will be embedded using an external URL. The images will be stored on the main Meadows web site in the https://www.meadowsps.com/site/support/screenshots/ folder. Screen shots should be named to briefly match the subject of the KB article, plus a sequential number (e.x. styleguide_1,jpg, styleguide_2.jpg, etc). Screen shot usage should be kept to a minimum to avoid maintenance issues. Please see separate style guide for screen shot creation (added directly below).

FOR KB ARTICLES:

1) Keep InDesign in default screen mode (Medium Dark)
2) Set SnagIT prefs to share images in PNG format.
3) Capture full or partial dialog, whichever makes the most sense.
4) No borders (unless required for clarity or better looking screen shot).
5) No drop shadows.
6) Highlight color will be default SnagIT Red (RGB: 255, 89, 75).
7) Use square box to set off selections on dialog
8) Use line or arrow to point out features
9) Use 5pt width for lines, arrows, and boxes.
10) OK to use callouts but use the square version with centered text as shown below:
 

Movies (Heading 3/ 14pt)

Movies can be embedded using HTML embed code provided by our video hosting service. For this you will need to copy/paste the embed code from the site whilst editing the KB article in Source Code mode. An example movie is presented below:

TABLES

This section describes how to create a table using the alternating color bars. It also presents a summary of all KB style elements.

To create a table with alternating borders colors, edit in Source Code mode
and add the class=”mps-table” to the element, as in this example.
Also highlight the first row and identify it as a Header Row,
and make headings Bold face.

Element Styling Notes
Main Topic H2 IN CAPS  
Section H3  
Sub-Section H4  
Individual Item H5 with Indent  
     
Step-by-Step Numbered List with First Line Bold
  1. Step 1
    This is the first step
  2. Step 2
    This is the second step
Item List (bullet points) Bullet List
  • Item 1
  • Item 2
  • Item 3
     
Dialog Items Bold Any dialog item that can be referenced by the name of the item. A few common examples are described below.
Button Bold  
Popup Menu Bold  
Checkbox Bold  
Edit Text Item Bold  
Product Names
(initial reference)
Bold Bold face first reference, then plain afterward
Example: Introducing the CopyFit module! CopyFit is a great product for adjusting overset text after a Merge operation.
     
Menu Items Bold/Italic Example: Select the Variable Links menu item
Menu Paths Bold/Italic Example: Main Menu > Sub-Menu > Item…
Feature Name
(initial reference)
Bold/Italic Examples: Merge, Cut & Stack, Variable Link Report, Multi-up Imposition (bold/italic first time, plain afterward)
     
Literal Text (text you type in) “Blue/Quoted” Quote the text and use Dark Blue color. Example: Enter the text “New DDF Name” and click OK.
     
File and Folder Names Blue or Code Use Dark Blue color or Code Sample
Full Paths Blue or Code Use Dark Blue color or Code Sample
URL’s (examples, not hyperlinks) Blue or Code Use Dark Blue color or Code Sample
     
Hyperlinks Assign Hyper Link For hyperlinks, enter descriptive text and assign a hyperlink using the link tool panel. Use full paths to any document or web page. Always open hyperlink in a new browser window.
     
Example Data (Data File, etc) Code Choose Insert > Code Sample
Example Scripts Code Choose Insert > Code Sample
     
Important Notes Block Quote Select paragraph text and choose Format > Formats > Blocks > Block Quote
Screen Shots Insert Picture https://www.meadowsps.com/site/support/screenshots/kb_desc_#.jpg
Videos Edit Source Code (Copy/Paste Embed Code) Get embed code from video site. Copy/Paste in source code
Tables Edit Source Code (class=”mps-table”) Edit source code, modify table element to enter class. Example: <table class=”mps-table” …   >

 

SAMPLE STYLES

Headline 1 (Not Used)

This describes the start of the next section. Now is the time for all good men to come to the aid of their country.

HEADLINE 2

This describes the start of the next section. Now is the time for all good men to come to the aid of their country.

Headline 3

This describes the start of the next section. Now is the time for all good men to come to the aid of their country.

Headline 4

This describes the start of the next section. Now is the time for all good men to come to the aid of their country.

Headline 5

This describes the start of the next section. Now is the time for all good men to come to the aid of their country.

Headline 6

This describes the start of the next section. Now is the time for all good men to come to the aid of their country.