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.
Example Article

How to attach a purchase order to an invoice in Xero

Click Business > Invoices

Search for invoice

You can locate a specific invoice by entering a search term (such as the company name):

  1. Click Search,
  2. Enter keyword,
  3. Click the invoice you want to update.

Click the Attach icon

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.)

 

Example of headings for the Procedure––run a webinar...

Performed by Assistant

Performed by Marketing Manager

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.

 

Example Checklist Procedure

Procedure––sign up customer paying via invoice

Policy

  1. Customer must sign up for account and agree to terms and conditions
  2. All billing information is managed in billing software
  3. All invoices are sent from billing software

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:

Requestor is the account owner

Detailed description of what to do next goes here...

Requestor is NOT the account owner

Detailed description of what to do next goes here...

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.
Example text
  1. "Hi [name], for security reasons, our policy is that the current account owner needs to request a change in ownership.
  2. Question: Is the current owner available?"
    1. Not sure who the account owner is
      • Your current account owner is [provide only the account owner's first name]
        1. If the requestor knows who the account owner is
          • "Great! Can you ask [account owner] to submit the request? Once I receive that, I'll be able to make that change."
            • The account owner is NOT available Jump below to 3. No, the current owner is not available
        2. If the requestor still does NOT know who the account owner is
          • "OK. For security reasons, we will need for you to confirm the name of the account owner. Is there anybody on your team who might know the name of the account owner?"
            1. Yes––"Great! Can you ask that team member to contact me with any questions?"
            2. No––"OK. Do you know [provide the first name of an Admin on the account]?" >> Click for instructions
              1. Yes––"Great! Can you ask that team member to contact me with any questions?"
              2. No––"OK. Let me bring this up with a member of my team."
                • Escalate this ticket to your supervisor. How to escalate the ticket.
    2. Yes, the current owner is available
      • "Great! Can you ask that team member to contact me with any questions?"
    3. No, the current owner is not available (Doesn't work there anymore)
      • "OK. Do you or a team member have access to the previous account owner's email?"
        1. Yes––"Great! I'm going to send an email to that email address. Will you respond to the email with a confirmation?"
        2. No––"OK. I'm just going to confirm this request with the other Admins on the account." >> Click for instructions
          • Send email to all Admins on the account; copy/paste and personalize this script:

            Hi, there! My name is [your name] and I'm a support rep for ScreenSteps.

            I'm receiving a request from [name of requestor] to change the account owner to [name of proposed account owner]. Typically, we only allow the account owner to make this type of request; however, [Name of requestor] mentioned that [name of current account owner] is not available. So I want to confirm with you that this request is approved since you are one of the Admin on the ScreenSteps account.

            Thanks!

            [Your name]
            ScreenSteps Support
            1. You receive approval
              • Confirm the proposed account owner is an Admin. >> Click for instructions
                1. If proposed user is an Admin
                  1. Update the account owner
                  2. Inform caller that update was made
                  3. Ask if caller needs help with anything else
                2. If proposed user is not an Admin
                  • "Hmmm... it doesn't look like that user is an Admin. I can only select a ScreenSteps Admin user to be the new account owner. Are you able to create a new Admin user account for that individual?"
                    1. If yes, "Excellent! Can you create an Admin user account with that person's name and then let me know?" 
                    2. If no, "Do you know anybody on your team who can do that?"
                      1. If yes, "Great! Can you ask them to create an Admin user account for that person? Once that account is created, let me know and I can assign that person to be the account owner."
                      2. If no, "Ok. Unfortunately, our policy is that we cannot create an Admin user account on behalf of somebody else. Is there anyone else on your team who has a ScreenSteps user account that can create a new Admin user account? If not, let me bring this up to my team." >> Click for instructions
            2. You do not receive approval (or never hear back)
              • Create a task to follow up in 2 days to ask if they were able to get this resolved.

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

Overview of ScreenSteps

Basics of ScreenSteps 3
Using ScreenSteps 8
Helpful Tips 3
Webinars 2

Other Resources

Recently Updated Articles

More Recently Updated Articles
Still Need Help? Contact Us