Style Guide

From Swift Navigation Wiki
Jump to: navigation, search

Overview

This style guide applies to all online documentation generated in for Piksi.

Referencing Piksi

  • When you reference Piksi, do not use definite or indefinite article, simply refer to it directly as in: "Now that you have Piksi..."
  • When you reference the Piksi platform or the Piksi RTK kit (i.e. when Piksi is a modifier), use definite articles.

Structure

  • Where possible, write an overview section at the beginning that summarizes the key points in a paragraph. This should include:
    • What the reader will learn by reading this article.
    • What kind of commitment the reader will need to make.
  • Where possible, model user work flows. For example, if a user wants to understand logging, they need to know how to initiate it, where to find the results, and how to interpret results. The documentation should be written in that order.

Text

  • Use first person, singular to address the reader.
  • Follow basic Strunk and White style guide
  • Console tabs always appear in bold (Click on the Baseline tab)
  • Piksi status always appears in italics (Your Piksi will now enter Simulation Mode. Later on, you will achieve Fixed RTK status)
  • Direct text output by the console always appears in fixed width:
    • Your console will now read Piksi has successfully acquired 9 satellites
  • General emphasis always appears underlined (On the FTDI website, you must use version 2.2.18, not version 2.3.)

Links

  • Link to concepts or other documentation one time, on first reference. Repeat link in Overview if referenced there.
  • Link to external sources for basic GPS and RTK concepts that are not defined elsewhere within the Wiki.

Images

  • Prefer Swift style imagery for explaining concepts
  • Prefer CAD style imagery for hardware diagrams

Talk

Use Discussion for open issues on the current page.