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.

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.