Introduction

Welcome! This is the official Snapmaker English Writing Style Guide. It is not a comprehensive grammar handbook, nor an academic writing reference book. It proposes rules that help standardize Snapmaker's documentation written in English, and prepare them for future reuse and localization.

This guide is compiled based on the need for our documentation to be factual, versatile, and user-friendly. It assumes readers come from varying backgrounds, and not all of them are native English speakers. As such, it prefers simple words and grammatical structures over complicated and fancy ones; it includes rules that violate traditional English grammar, though very rarely.

The Language and Grammar chapter outlines rules that govern right or wrong, while the Formatting and Content Planning chapter stipulates rules that determine good or bad. The sections are organized in alphabetical order. The latter half is a Chinese translation of the guide. For Snapmaker Chinese Writing Style Guide, visit https://github.com/Snapmaker/Snapmaker-Chinese-Writing-Style-Guide.

As of November 12, 2020, the Shimo copy of this guide is no longer being monitored. Any change made will be made on this Github repository. Any suggestions to make it better are welcome. And to report bugs or propose ideas, file an issue first, or email at ginger@snapmaker.com.

Below is a Table of Contents which helps you navigate.

1. Language and Grammar

• 1.1 Abbreviation

• 1.2 Agreement

  • 1.2.1 Pronoun-antecedent Agreement
  • 1.2.2 Subject-verb Agreement

• 1.3 Articles

• 1.4 Modifiers

  • 1.4.1 Misplaced Modifiers
  • 1.4.2 Multiple Modifiers
  • 1.4.3 Noun Modifiers

• 1.5 Readability

  • 1.5.1 Be Brief
  • 1.5.2 Be Precise
  • 1.5.3 Be Thoughtful

• 1.6 Spelling

  • 1.6.1 Numbers
  • 1.6.2 Units of Measure

• 1.7 Tone

2. Formatting and Content Planning

• 2.1 Capitalization

  • 2.1.1 Dates and Times
  • 2.1.2 File Name Extensions
  • 2.1.3 Lists
  • 2.1.4 Notes
  • 2.1.5 Proper Nouns
  • 2.1.6 Texts in a Table
  • 2.1.7 Titles and Headings
  • 2.1.8 Units of Measure

• 2.2 Notation

  • 2.2.1 Admonitions
  • 2.2.2 Emphasis and Reference

• 2.3 Organization

  • 2.3.1 Headings
  • 2.3.2 Links
  • 2.3.3 Lists
  • 2.3.4 Tables

• 2.4 Punctuation

  • 2.4.1 Ampersand (&)
  • 2.4.2 Angle Bracket (>)
  • 2.4.3 Asterisks (*)
  • 2.4.4 Colons (:)
  • 2.4.5 Commas (,)
  • 2.4.6 Ellipses (...)
  • 2.4.7 En dashes (–)
  • 2.4.8 Em dashes (—)
  • 2.4.9 Exclamation points (!)
  • 2.4.10 Hyphens (-)
  • 2.4.11 Multiplication Sign (×)
  • 2.4.12 Parentheses ()
  • 2.4.13 Periods (.)
  • 2.4.14 Quotation marks ("")
  • 2.4.15 Semi-colons (;)
  • 2.4.16 Slashes (/)

• 2.5 Spacing

Chinese Translation