ScreenSteps

Example of a Style Guide

Updated on

Use this style guide when writing these three types of articles:

  1. Answering a "How do I do this in the product?" question
  2. Checklist procedure
  3. Call flow

Goals

  • Conciseness
  • Clarity
  • Visually logical
  • Use tools to create at-a-glance comprehension when possible
  • Comprehensive information which is easy to access when necessary

1. Answering a "How do I do this in the product?" question

This type of article explains how to use a product. The end-user knows what she wants to do––she just doesn't know how to do it in the product. For example, if a customer knows that she wants to add more Editors in ScreenSteps but isn't sure how to do it, you would refer her to this type of article.

These articles are generally short. Each heading briefly explains an action and quickly guides the end user through a series of steps.

1.1. Title

  1. Start the title with "How to"
  2. Only the first letter in the title is capitalized, except for proper nouns.
  3. Make the title very specific to the action and where the action is taking place.

Example: How to add new editors in ScreenSteps

1.2. Introduction

  1. Writing an introduction is optional
  2. use the Introduction style

1.3. Headings

Capitalization

  1. First letter of a sentence
  2. Proper nouns
  3. Elements on a screen (buttons, tabs, etc.)

Wording and formatting

  1. Start the heading with an action verb such as "Click" or "Navigate" or "Scroll."
  2. Each heading is short.
  3. Do not include the preposition "on" (example: Click on the button––instead, Click the button).
  4. Use > when describing a series of clicks. Example: Click Home > Profile > Action.

Example of a heading: Click Account Settings

1.4. Paragraph text

Capitalization

  1. First letter of a sentence
  2. Proper nouns
  3. Elements on a screen (buttons, tabs, etc.)

Wording and formatting

  1. Bold words that describe areas of screen that are clicked. Example: Click Account Settings to see a list of options.
  2. Use numbered lists when describing a series of steps that must be done in order.
  3. Use bulleted lists for descriptions with no particular order.
  4. Match numbered list to sequencing annotations on screenshots
  5. Use > when describing a series of short clicks. Example: Click Home > Profile > Action.

1.5. Tables

  1. Use tables to describe what should be typed in fields fields on a form.
  1. Hyperlinks to other knowledge base articles that provide explanations which enhance the content within the article should be inline links.
  2. Hyperlinks to other knowledge base articles that direct a reader to more relevant content should open a new tab/window.

1.7. Foldable sections

Additional information that is helpful, but not pertinent, can be included as a foldable section.

1.8. Paragraph styles

Helpful tips that improve a workflow should use the Tip style.

Information that a reader needs to perform a task should use the Info style.

Critical steps that must be followed should use the Alert style.

Critical information that must be known should use the Warning style.

1.9. Screenshots

  1. Screenshots should be no wider than 800 pixels
  2. Use a screenshot for each major on-screen action.
  3. Use multiple screenshots in the same block to demonstrate a sequence.
    • If multiple screenshots are used, include a drop shadow for each screenshot.

1.10. Annotations

  1. Use annotation presets.
  2. Do not use more than 4 sequence annotations on a single screenshot.
  3. Use Arrows to point out parts of the screen that need to be clicked or fields that need to be entered.

2. Writing a checklist procedure

This type of article explains how to perform a repeatable task that does not have variation. The end-user receives an input or a request and must follow a series of tasks to execute the request. The tasks are generally the same, regardless of the inputs.

For example, when an employee is asked to run a webinar, he would reference a checklist, which would run through a series of tasks such as "Create webinar" and "Announce webinar."

Checklist items are not individual clicks such as "Login" or "Click Opportunities." Rather, checklist items are entire tasks such as "Create subscription in billing software."

2.1. Title

  1. The title includes name of a procedure, not the specific tasks.
  2. Only the first letter in the title is capitalized, except for proper nouns.
  3. Include the term "procedure" at the beginning of the title.

Example: Procedure––run a webinar

2.2. Policy

  1. Include a policy heading.
  2. Write out the policy as a numbered list.
  3. Use the introduction style.

2.3. Headings

  1. Headings are only used to distinguish different roles or timing of a procedure. Only include headings if two or more roles are being explained in a procedure, or if a procedure takes place over two or more periods.

Capitalization

  1. First letter of a sentence
  2. Proper nouns
  3. Elements on a screen (buttons, tabs, etc.)

 

2.4. Paragraph text outside of checklist item

Capitalization

  1. First letter of a sentence
  2. Proper nouns
  3. Elements on a screen (buttons, tabs, etc.)

Wording and formatting

  1. Bold words that describe areas of screen that are clicked. Example: Click Account Settings to see a list of options.
  2. Use numbered lists when describing a series of steps that must be done in order.
  3. Use bulleted lists for descriptions with no particular order.
  4. Match numbered list to sequencing annotations on screenshots
  5. Use > when describing a series of short clicks. Example: Click Home > Profile > Action.

2.5. Paragraph text within checklist item

  1. Follow the guidelines for paragraph text outside of checklist item.
  2. The paragraph text within a checklist item should be specific to the checklist item task.
  3. If you have a knowledge base article that explains how to perform the checklist item task (e.g. Create a webinar), then provide an inline hyperlink to the article.

2.6. Tables

  1. Use tables to describe what should be typed in fields fields on a form.
  1. Hyperlinks to other knowledge base articles that provide explanations which enhance the content within the article should be inline links.
  2. Hyperlinks to other knowledge base articles that direct a reader to more relevant content should open a new tab/window.

2.8. Foldable sections

Additional information that is helpful, but not pertinent, can be included as a foldable section.

2.9. Paragraph styles

Helpful tips that improve a workflow should use the Tip style.

Information that a reader needs to perform a task should use the Info style.

Critical steps/information that must be followed should use the Alert style.

2.10. Screenshots

  1. Only include screenshots for tasks/actions that are unique to the checklist item––otherwise, reference an existing article.
  2. Screenshots should be no wider than 800 pixels
  3. Use a screenshot for each major on-screen action.
  4. Use multiple screenshots in the same block to demonstrate a sequence.
    • If multiple screenshots are used, include a drop shadow for each screenshot.

2.11. Annotations

  1. Use annotation presets.
  2. Do not use more than 4 sequence annotations on a single screenshot.
  3. Use Arrows to point out parts of the screen that need to be clicked or fields that need to be entered.

 

3. Writing a call flow article

This type of article helps employees and customers navigate through a procedure that changes based on inputs and variables.

3.1. Title

  1. The title includes name of a procedure, not the specific tasks.
  2. Only the first letter in the title is capitalized, except for proper nouns.
  3. Include the term "procedure" at the beginning of the title.

Example: Procedure––run a webinar

3.2. Policy

  1. Include a policy heading
  2. Write out the policy as a numbered list
  3. Use the introduction style

3.3. Procedure

Include a procedure heading.

3.4. Decision statement

Under the procedure heading, write a statement that requires the reader to identify a variable or an input.

Example: When asked to change the account owner to a new user, first verify whether the requestor is currently the account owner.

3.5. Foldable sections

Include a foldable section for each option.

Example:

3.6. Paragraph text - General

Capitalization

  1. First letter of a sentence
  2. Proper nouns
  3. Elements on a screen (buttons, tabs, etc.)

Wording and formatting

  1. Bold words that describe the main actions that are taken. Example: Click Account Settings to see a list of options.
  2. Use numbered lists when describing a series of steps that must be done in order.
  3. Use bulleted lists for descriptions with no particular order.

3.7. Paragraph text - Instructions

  1. Black for all general instructions
  2. Red for instructions that should be addressed with sensitivity and tact
  3. Green for instructions indicating a smooth path toward resolution or completion
  4. Italicize text that is meant to be spoken.

3.8. Tables

  1. Use tables to describe what should be typed in fields fields on a form.
  1. Hyperlinks to other knowledge base articles that provide explanations which enhance the content within the article should be inline links.
    • Include ">> Click for instructions" and hyperlink the text to the article.
  2. Hyperlinks to other knowledge base articles that direct a reader to more relevant content should open a new tab/window.

3.10. Paragraph styles

Helpful tips that improve a workflow should use the Tip style.

Information that a reader needs to perform a task should use the Info style.

Critical steps/information that must be followed should use the Alert style.

3.11. Screenshots

  • Use screenshots sparingly in call flow articles.
  • Screenshots should be no wider than 800 pixels
  • If multiple screenshots are used, include a drop shadow for each screenshot.

3.12. Annotations

  1. Use annotation presets.
  2. Do not use more than 4 sequence annotations on a single screenshot.
  3. Use Arrows to point out parts of the screen that need to be clicked or fields that need to be entered.

 

You are done. Great job!

0 Comments

Add your comment

This site is protected by reCAPTCHA and the Google Privacy Policy and Terms of Service apply.

Previous Article Go Live Checklist
Next Article Bookmark Your ScreenSteps Admin Area
Still Need Help? Contact Us