Documentation style guide

Language and terminology styles

• Top level headings use Sentence case. (Note: as of 1/4/18, we have a mix of title and sentence case. Needs to be improved.)
• All other headings use Sentence case, where only the first word and any proper nouns have a capital letter.
• Use capitalization only for a proper noun, and use throughout. For example, "stack" should almost always be lowercase in text

Referring to "things"

• References to the Pulumi CLI or CLI commands should be enclosed in backticks (e.g., pulumi update).
• References to UI elements within a webpage should be bold. (e.g., "Go to the Account page in the Pulumi Console and select sync profile with GitHub").
• Use arrows to indicate a navigation. (e.g., "Go to FooPage -> BarItem").

Formatting

• Use hash marks for headings (#, ##, etc)

• Use double-asterisks for bold **

• Use underscore for italic _

• Use triple-backtick and language for code formatting, e.g. ```typescript

• Don't use hard linebreaks. They are discouraged by the the kramdown formatter, which calls it "lazy syntax". See kramdown Syntax.

• In contrast to GitHub-flavored markdown, use two spaces after a list item, so that the indentation of the next level aligns correctly. This is because kramdown parses lists differently than GitHub. See http://idratherbewriting.com/documentation-theme-jekyll/#markdown.

  I.e., do 1. First item (two spaces)

  Instead of 1. First item (one space)

Sections

If a tutorial has more following tutorials, use a Next steps section at the end. If you're linking to other reference material, use Learn more.