technical-writing-cheatsheet.md

Camunda style guide cheat sheet

Overview

A quickstart to the complete Camunda 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. :::
Breaking changes	If you are documenting a breaking change, please ensure this is noted in appropriate/relevant docs outside of solely update guides and announcements.	N/A	N/A
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 and gifs	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. Gifs are strongly discouraged in place of text for maintainability and accessibility purposes.	Avoid blurry screenshots. Avoid including any personal information in your images. If a username must be included, use "My organization". 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
OpenSearch	OpenSearch is the flexible, scalable, open-source way to build solutions for data-intensive applications.	N/A	N/A