Write Official Writing Style Guide

[jennifer-shehane]

Rough draft for initial outline:

Voice

• Cypress communicates in a casual but professional way.
• Content should always have substance, to create a sense of trust, credibility and understanding.
• The voice is more friendly than formal. Imagine the brand persona speaking - a real person.
• Contractions are fine - e.g. ‘isn’t’, ‘can’t’ as they sound more natural and fit our brand personality.
• Tone is mostly serious, but light-heartedness comes through every now and then.
• Humor can be used when appropriate, particularly when talking about typical situations users face.
• Humor should not be mocking, although light sarcasm is OK. Positive humor (e.g. puns, witty banter) is preferable.
• Use up-to-date terminology from the industry to show awareness of current trends.
• Language should convey a deep knowledge of the industry. Because our audience is techie, we can use industry terminology and jargon.
• Copy should convey energy and enthusiasm and be predominantly positive.
• Copy should always be succinct, very clear and on point.
• Avoid run-on (long, compound) sentences. Keep it to one message per sentence.
• Use devices like headings, sub-headings, call-out boxes, quotes and bullet points to make the copy easy to scan.

Code Style

• single quotes over double quotes
• no semicolons
• When referring to an api command - if command can only be chained only off of other command (child command) - display without cy prefix: Example: .as(). If command can only be chained off cy (parent command) reference as cy.window(). If both combo command - write without cy prefix: Example: .contains()
• command chaining convention - always start parent commands on a new line, chained off of cy.
• Width: 80 characters wide tops
• Prefer js to javascript when targeting the language for a code block. (Less to type and read.)

Conventions

• internet with a lowercase ‘i’
• open source
• front end
• end-to-end
• Emojis can be used, but sparingly.
• Prefer American English over British English.
• Display lists (options, flags, etc) and tables in alphabetical order.
• Use sentence case in headings

Product Terminology:

• Uppercase Cypress for the product, lowercase cypress for the executable/module.
• Dashboard Service
• Test Runner
• Command Log
• CLI

[richdouglasevans]

This is great Jennifer, thank you 👍

[richdouglasevans]

Just adding stuff here that seems relevant as I come across it.

Do strikeout / delete stuff that's not in keeping with the way you want it 👍

Code Style

• Width: 80 characters wide tops
• Prefer js to javascript when targeting the language for a code block. (Less to type and read.)

Conventions

• Uppercase Cypress for the product, lowercase cypress for the executable/module.

[richdouglasevans]

Another one for Conventions

• Use sentence case in headings