Skip to content

Latest commit

 

History

History
76 lines (57 loc) · 2.87 KB

style-guide.md

File metadata and controls

76 lines (57 loc) · 2.87 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.
    • 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">.
  • Put a 1-pixel black border around all images. You can use the command line utility, Bordify.

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

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.

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"

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.