Documentation guide

This information explains how to contribute to the OpenSwitch OPX documentation project. OPX uses the open-source GitHub Markup library so you can write in Markdown, RST, Textile, or any other supported format.

Not explained here are the basics — create repositories, branches, commit changes, and so on (see Hello World for basic GitHub collaboration). Use the preferences below to write effective and easy-to-read documentation which follow the OPX standards and styles.

Preferences

• Don't use h1 — use h2 (## This is a title) for easy reading
• Use h3 for step headings — aids readability (see example below)
• Sentence-case titles only — aids readability and simplifies organization
• Keep titles under five words — aids readability and simplicity
• Write in active voice — anything ending in ing or ed is passive
• Only one space after each sentence — no need to use two spaces
• Write in first person — explain how you would complete steps
• All paths should be in italics — use underscore before and after the path
• Don't leave single sentences hanging — combine with relevant information for readability
• All code examples are indented four spaces — automatically adds grey box around code (see example below)
• Step numbers should appear in bold (1) — helps step numbers stand out
• Think of your audience while writing — include enough information to support concepts
• Don't bold punctuation — no reason to bold periods in steps or colons
• All code within sentences (not steps) is tagged as Code ($ sudo) — aids readability and helps developers quickly identify code
• Write casually and have fun — use contractions and explain in simple terms (as you would to a peer)

OPX repository example

1. Configure /etc/apt/sources.list to point to the external OPX package repository.

deb http://dl.bintray.com/open-switch/opx-apt jessie main
deb https://dell-networking.bintray.com/opx-apt jessie main

2. Upgrade the pre-installed OPX package.

sudo apt-get update
sudo apt-get upgrade
sudo reboot

Capitalization

• ACL — not Acl or acl
• API — not api
• Linux — not linux or LINUX
• NETCONF — not Netconf or netconf
• QoS — not qos, Qos or QOS
• URL — not url or Url
• YANG — not Yang or yang

Notes

All notes or important information is tagged as Blockquote (>) to stand out and be easily noticed.

This is important information.