Skip to content

Latest commit

 

History

History
49 lines (36 loc) · 14.4 KB

technical-writing-cheatsheet.md

File metadata and controls

49 lines (36 loc) · 14.4 KB

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.
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