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.
Our primary goal in documentation is to achieve organization, clarity, and direction.
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. |
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. |
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 |
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 |