technical-writing-cheatsheet.md

Tech Writing Cheat Sheet

Overview

A quickstart to the complete Camunda Writing Style Guide. The following document outlines writing techniques Camunda utilizes to ensure uniform styling across Camunda documentation for a more cohesive and organized user experience alongside a fast-growing staff.

Goal

Our primary goal in documentation is to achieve organization, clarity, and direction.

Grammar

Subject	Practice	Avoid	Example/Use
Bolding	Bold when referring to button names or items to select.	Click "Create New Diagram."	Click Create New Diagram under the Diagrams tab.
Italics	Use when applying emphasis to a word.	Click Create New Diagram.	Click Create New Diagram.
Numbers	Write whole numbers one through nine in full. Write whole numbers 10 and upwards as numerals.	In this example, we will create 1 diagram.	In this example, we will create one diagram.
Spelling	Default to American spelling and US English. Visit the Oxford American Dictionary for details.	Analyse Bernd Rücker	Analyze Bernd Ruecker
Voice/Tense	Second person, active voice.	I, me, my. The computer is turned on by pressing the power button.	You, your. Press the power button to turn on the computer.

Punctuation

Subject	Practice	Avoid	Example/Use
Commas	Camunda uses the Oxford comma. Use a comma to separate independent clauses when they are joined by coordinating conjunctions like and, but, for, so. Use a comma to separate a sentence introduction from the remainder of the sentence content (Therefore, Thus, As a result, So, Henceforth,)	Camunda loves its products, GitHub and Google Analytics. We want to automate a process so let’s start by creating an account.	Camunda loves its products, GitHub, and Google Analytics. We want to automate a process, so let’s start by creating an account.
Hyphens	Use the hyphen (-) to create a compound adjective (two describing words together).	User friendly interface.	User-friendly interface.
Quotation marks	Only use double quotations to illustrate the words spoken by another individual.	Navigate to the "Decisions" section.	Navigate to the Decisions section.

Formatting, organization and structure for conceptual pieces and implementation steps

Subject	Practice	Avoid	Example/Use
Admonitions	Utilize the note admonition to separate important notes in documents according to Docusaurus’ guidance.	Note: This is the bpmnProcessId, you'll need to create a new instance.	:::note This is the bpmnProcessId, you'll need to create a new instance. :::
Button names	Click Next. Use the arrow icon > to list out a series of buttons the user needs to press.	Italics and quotes. Click "Next" and then select "Open" and press "Enter".	Click Next > Open > Enter
Filenames	Place filenames within a code block.	Avoid bolding or italicizing filenames.	Open codeStuff.txt In the Name box enter project1.
Images	Ensure your images are appropriate in size and clarity. All images should include alt text. Crop the user bar and any personal information out of your photo or screenshot.	Avoid blurry screenshots. Avoid including any personal information in your images. Avoid images that are unnecessarily large or bulky to keep the page clean and concise.	N/A
Titles and headers	Sentence case spelling in titles and headers. For sentence case spelling, only capitalize the first word and any proper nouns.	How To Open A File Our travel guide to berlin, germany	How to open a file Our travel guide to Berlin, Germany

Product names and other terminology

NOTE: This section is an overview of a few commonly misunderstood Camunda terms. Refer to this summary of OMG specifications when referring to acronyms within your documentation.

Term/Acronym	Meaning	Avoid	Use
Cluster	A cluster represents a configuration of one or more brokers collaborating to execute processes.	Avoid using capitalized "Cluster" when it is not the first word in a sentence. This also applies to terms like process instance and task.	"Zeebe implements the Gossip protocol to know which brokers are currently part of the cluster."
Elasticsearch	A free, open, and multitenant-capable search engine.	Elastic search, ElasticSearch	Elasticsearch
GitHub	A provider of internet hosting for software development.	Github	GitHub
REST API	A software style to create interactive applications.	Rest API, Rest API, Rest Api	REST API, pluralized REST APIs
Type	A data type. For example, a string, boolean, or integer.	Avoid confusion between type and value when outlining APIs and query parameters. See the term Value in this table for proper usage below.	Type
Value	For example, the default value or given value of a particular query or task object.	Avoid confusion between type and value when outlining APIs and query parameters. See the term Type in this table for proper usage above.	Value