Lab Style Guide

Generally the Lab Style Guide follows the Cisco Style Guide. This link is available on a Cisco network only.

Headings

For the sake of consistency, we require that authors include the following headings in every lab:

• Objectives
• Prerequisites
• Step n: Title of step

Capitalization

The following terms are capitalized when referring to DevNet offerings:

• Sandbox
• Learning Lab
• Module
• Track

Generally the Learning Labs headings should follow initial capitalization, also known as "sentence case," which is described in the Cisco Style Guide.

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

The code types you can declare with triple backticks are documented in: http://highlightjs.readthedocs.io/en/latest/css-classes-reference.html

Images

When to use images

Use diagrams sparingly. Use them when there is evidence of a complex process or workflow. Use them when there is a configuration or reference architecture that needs clarifying visually. Do not use diagrams when a workflow is simplistic or when the object can be explained in text.

Use screenshots sparingly and crop to the meaningful part of the screen. You may annotate screenshots but do so rarely, instead preferably the screenshot shows the meaningful action area of the screen.

How to create images

Here are suggestions for tools and file formats. In open source communities, they use draw.io and require svg files to be stored with the source files, and output to png. For screenshots, .png is sufficient. You can use animated .gif files if you are willing to maintain those going forward and re-capturing when needed. SnagIt is a common tool for animated captures.

Image style

Use a transparent background, landscape orientation, and ensure images are no wider than 900pt width and height.

Fonts on images

Use Cisco Sans for any labels in an image. Font size must be 8 px or higher.

Command markup

You should specify whether a command is in bash or a snippet of Python code that can be run in a Terminal window using these indicators.

Triple-back-tick bash indicates that the command can be copied to the developer environment. You should not include the prompt such as $ in the command.

```bash
python exercise1.py
```

Triple-back-tick python indicates that the command can be run in a Python IDE.

```python
def macaddresses_seek():
```