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)
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.
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.
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.
A dialog item is any item that interacts with the user on a dialog or panel window. Such items include the following:
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.
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.
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.
When referencing the name of a Feature for the first time, such as Cut & Stack, PPML 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.
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.
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.
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...
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)
This section lists example styling for step-by-step instructions. The general way to approach this will be as follows:
Here is item 1 (use 8 spaces to indent with preceding shift-return)
Here is item 2
Here is item 3
Now here is a list of the same steps but only as single line.
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.
This section describes how to position screen shots and embedded movies.
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:
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:
This section describes how to create a table using the alternating color bars. It also presents a summary of all KB style elements.
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 |
|
Item List (bullet points) | Bullet List |
|
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” … > |
This describes the start of the next section. Now is the time for all good men to come to the aid of their country.
This describes the start of the next section. Now is the time for all good men to come to the aid of their country.
This describes the start of the next section. Now is the time for all good men to come to the aid of their country.
This describes the start of the next section. Now is the time for all good men to come to the aid of their country.
This describes the start of the next section. Now is the time for all good men to come to the aid of their country.
This describes the start of the next section. Now is the time for all good men to come to the aid of their country.