Learning Lab Style Guide

Overall, the Learning Labs should follow the Cisco Style Guide for writing style.

Generally this guidance means you should:

• Write in active voice.
• Use serial commas, matching The Chicago Manual of Style with Cisco amendments from the Cisco Style Guide.
• For list items, write and punctuate all items consistently in parallel. If any item in the list requires a period, add periods to all the items.
• Avoid nesting more than two list levels.
• Use gender-neutral writing.
• Use American English.

Headings

For the sake of consistency, we require that you as an author include the following headings in every lab:

• Objectives
• Prerequisites
• Step Nn

Objectives

Use a bullet list to explain the learning objectives of the lab. These are the skills or knowledge you expect the student to walk away with after completing the lab. Make this short and to the point. Typically there are 1-4 objectives. List the objectives in the same order that the topics are covered in the lab.

Example

After completing this lab you will be able to:

• Make API calls to an ACI server
• Understand the API Object Model and its tree structure
• Identify ACI Objects by Name and Class

Estimated Time (Deprecated)

The older lab templates have a place for putting the estimated time that it takes to complete the lab.

DO NOT included the estimate time. The estimate time is now pulled automatically from the lab's JSON file. We don't want potential inconsistency between the time stated in the lab, and the time in the JSON file. For that reason, the only place you as an author should put the estimate time is in the lab's JSON (metadata) file.

Prerequisites

List any required tools, knowledge, or skills that the student should have before starting the lab.

Step Nn

Each page of the lab correlates to a major step.

Page one should have a Heading 1 labeled Step 1: blah blah text.

The top of page 2 should have a Heading 1 labeled Step 2: blah blah.

Try to start each step's description with a gerund, that is a verb ending with -ing.

Example markdown

Page 2 of the lab (top of the page)

 # Step 2: Installing Python
 
 To install Python: 
    1. Go to python.org
    2. Click on the download page
    ...

Page 3 of the lab (top of the page)

 # Step 3: Launching Python
 
 To launch Python: 
    1. Open a terminal window.
       In Windows, open a command window.
       In Mac OS or Linux, open a terminal window.
    2. Type the command:
    ...