Skip to content

Latest commit

 

History

History
102 lines (75 loc) · 3.68 KB

style-guide.md

File metadata and controls

102 lines (75 loc) · 3.68 KB
Raw

Style Notes for Tile Authors

This topic provides style guidelines to follow when writing documentation for Pivotal Partner tiles.

In this topic:

Punctuation

  • Use the serial or Oxford comma.
    • Correct: "x, y, and z"
    • Incorrect: "x, y and z"
  • Don't use parentheses unless you are indicating an acronym.
    • Example: "Pivotal Cloud Foundry (PCF)"
  • Don't use slashes; write "and" or "or".
  • Don't use "&" ; write "and".
  • Capitalize main words in headings. Use Chicago style. If you are unsure, use an online tool, such as Capitalize My Title.
    • Correct: Using the Squidsoft Dashboard
    • Incorrect: Using the Squidsoft dashboard

Images

  • In Markdown, you can code images as follows: ![ALT-TEXT](IMAGE-FILE.png).
    • Except for html tables, wherein you code images as follows: <img src="IMAGE-FILE.png" alt="ALT-TEXT">.

Verbs and Tenses

  • Don't use future tense when you can use the present tense.
    • Correct: "A pop-up appears."
    • Incorrect: "A pop-up will appear."
  • Don't use contractions like "don't".

Formatting

  • Use bold when referring to UI text.
  • Don't put quotes around UI elements.
  • Don't use italic.
  • Keep lines short in the source file. Fewer than 100 characters is preferred.
  • When formatting commands, use the house style shown in Documenting Commands.

Procedures

  • Make sure that everything the reader has to do is written in the imperative and placed in a numbered step.

  • Use the imperative for headings of sections that contain procedures.

    • Correct: "Install Squidsoft"
    • Incorrect: "Installing Squidsoft"

  • Use the gerund for topic titles if the topic contains procedures.

    • Example: "Using Squidsoft"

    Do not use gerunds for headings within a topic.

  • Always put some introductory text between a title and the first step of a procedure.

    • Example: "To migrate from one service instance to another, do the following:"

Dates

Spell out dates with the full month, day, and year. For example:

  • September 29, 2018
  • May 1, 2017

Legal Issues

  • Always use your product name (and our product name) correctly.
  • If you choose and abbreviated form of the name, spell out the product name in full in its first use in body text on each page, with the abbreviated version in parenthesis after it.
    • Example: "Pivotal Cloud Foundry (PCF)"
  • If you choose to use a trademark for your product name, add the trademark only to the first use in body text on each page.
  • Never mention features that you intend to include in a future release.

Language Tips

  • Don't use "we".

    • Correct: "YOUR-COMPANY-NAME recommends..."
    • Incorrect: "We recommend..."

  • Spell out most acronyms when first used in body text on a page.

    • Example: "application security group (ASG)"
    • Example: "availability zone (AZ)"

  • For more tips about language, see Word and Phrase List: Public Facing.

Cross-References

This document describes how to format cross-references:

Formatting Cross-References