diff --git a/howtos/technical-writing-styleguide.md b/howtos/technical-writing-styleguide.md index c13a71f96f9..c0e8cb73d7e 100644 --- a/howtos/technical-writing-styleguide.md +++ b/howtos/technical-writing-styleguide.md @@ -19,13 +19,14 @@ The Camunda Style Guide applies primarily to the following: - Press releases - Whitepapers - Case studies +- UI text within the product ## Objectives We encourage document authors and technical writers to keep in mind grammar, punctuation, formatting, and terminology to create user-friendly documentation between developers and users. With these tools in mind, our goal is to achieve four key objectives in our technical writing: | Goal | Questions to ask | -| ------------ | ----------------------------------------------------------------------------------------------------------------------------------------------- | +| :----------- | :---------------------------------------------------------------------------------------------------------------------------------------------- | | Objective | Is there a clear objective, whether a learning objective or key takeaways? Are they summarized clearly in the intro and conclusion? | | Organization | Is the documentation organized? Is the flow of information logical? Have I broken large components into smaller, simpler components? | | Clarity | Is the information clear? Have I spelled out acronyms and avoided too much company jargon or slang? Does the reader understand what I'm saying? | @@ -35,25 +36,26 @@ We encourage document authors and technical writers to keep in mind grammar, pun ## Grammar -| Subject | Practice | Avoid | Example/Use | -| -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| Bolding | Bold when referring to button names or items to select.
Bold to refer to another section within a document. If you are referencing another document entirely, link to it. | Click "Create New Diagram." | Click **Create New Diagram** under the **Diagrams** tab. | -| Capitalization | Refer to [Purdue's American capitalization guide](https://owl.purdue.edu/owl/general_writing/mechanics/help_with_capitals.html). | i like Camunda 7. | I like Camunda 7. | -| Currency | Use the currency symbol first, followed by the amount. Where appropriate, round to a whole number. | I have two hundred dollars. | €300
$22,600
€22.6 million | -| Dates | -| Avoid expressing a month as a number to avoid common confusion around US/EU conventions. If there is no way around it, use the US-English “/” as separators for all content (such as marketing materials) with the exception of technical documentation (guides, manuals, etc.)
In technical documentation, use "-" as separators as it mirrors most timestamps in various programming languages. Also note that it may be best to remove the day of the week as it may not be as relevant as the day and month. | 10 December, 2018 | December 10, 2018 | -| Date ranges | Avoid repeating the same month twice in the same date range.
If you are using numerical values, enter as follows: Year, month, date. | Camunda Community Summit April 27 - April 28 | Camunda Community Summit April 27-28 | -| Genders | Our default is to optimize for gender neutral writing in most cases, unless a person has specified their pronouns in advance. | He/she | A group of people/a person: They
A business: It
A user: The user, they | -| [In to vs. into](https://www.grammarly.com/blog/into-vs-in-to/) | Always think of "into" as a single preposition (within or outside of something.)
Typically, "into" refers to physically going inside.
Think of "in to" as two independent prepositions that happen to end up next to one another, and typically aren't physically entering or exiting something.
Oftentimes, you can tell if you should use "in to" because you could place a comma after "in," and the sentence would still make sense. | Type your name in to the text box to sign up for Camunda 8.
"Check which folder the file is into ensure you are in the correct location." | Type your name into the text box to sign up for Camunda 8.
"Check which folder the file is in to ensure you are in the correct location." | -| Italics | Use when applying emphasis to a word. | Avoid overuse, using for button names.
Click _Create New Diagram_. | See the **Bolding** section in this style guide above.
Click **Create New Diagram** under the **Diagrams** tab.
"You _must_ ensure your environment is configured correctly before moving forward through the steps below." | -| Numbers | Write whole numbers one through nine in full.
Whole numbers 10 and upwards are written as numerals.
Large numbers may be written as numerals with definition (million, billion).
Currency does not follow the same rules. See details in the sub-section titled **Currency** above this table. | In this example, we will create 1 diagram and eleven processes to help 1,000,000 customers. | In this example, we will create one diagram and 11 processes to help 1 million customers. | -| Percentages | Written as % and always in numerals. | 10 percent | 10% | -| Pronoun references | Unclear pronoun reference occurs when a pronoun (often "it," "this," "that," or "they") could refer to more than one subject in a sentence, according to practice by [English Composition](https://englishcomposition.org/essential-writing/unclear-pronoun-reference/). Practice clarifying these pronouns, and removing them where appropriate. | After you execute `npm start`, you can run it.
In the example above, what exactly are we running? | After you execute `npm start`, you can run the program.
In the revised example above, we removed the unclear pronoun. | -| Spacing | Following a period, it is standard to have _one_ space before beginning a new sentence. | Avoid using two spaces after a period: "Message correlation is a powerful feature in Camunda 8. It allows you to target a running workflow with a state update from an external system asynchronously." | "Message correlation is a powerful feature in Camunda 8. It allows you to target a running workflow with a state update from an external system asynchronously." | -| Spelling | Default to American spelling and US English.
See details in the sub-section titled **Spelling** below this table. | Analyse
Colour
Capitalise
Humour
Bernd Rücker | Analyze
Color
Capitalize
Humor
Bernd Ruecker | -| Times | Use the 12-hour clock, preferably UTC, and uppercase AM or PM where necessary. Always use the corresponding time zone if necessary. See this useful list of [standard abbreviations](https://www.timeanddate.com/time/zones/) for time zones.
Be mindful of time zones when writing about events that occur across multiple borders. We aren't imposing any hard and fast rules, because we're dealing with global time zones and hundreds of conventions as a remote-first company.
Standardizing on timezones, we typically communicate in or default to CET/CEST, EST/EDT, and PST/PDT.
CET or CEST is used depending on daylight savings time, CEST indicating Central European Summer Time.
EST/EDT and PST/ PDT are used depending on daylight savings time, EDT/PDT indicating daylight savings. | Avoid using hyphens to display time periods. Instead, use an en dash.
To type an en dash on your Mac, type Option+Minus (-). To type an en dash on Windows, hold down Alt and type 0150 on the numeric keyboard; the en dash will appear upon releasing the Alt key. | 1 p.m. CET
10 a.m. PST | -| Voice/Tense | Second person, [active voice](https://www.grammarly.com/blog/active-vs-passive-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. | -| Years | Don’t use an apostrophe for years. | 1960's | 1960s | +| Subject | Practice | Avoid | Example/Use | +| :-------------------------------------------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| Bolding | Bold when referring to button names or items to select.
Do not use bold to reference another section within the same document. Instead, link to the relevant section or another document using descriptive link text. | Click "Create New Diagram." | Click **Create New Diagram** under the **Diagrams** tab. | +| Capitalization | Refer to [Purdue's American capitalization guide](https://owl.purdue.edu/owl/general_writing/mechanics/help_with_capitals.html). | i like Camunda 7. | I like Camunda 7. | +| Contractions | Use common contractions in user-facing instructional content to maintain a natural, conversational tone. | Avoid overly formal or robotic language by omitting contractions where they would naturally occur in speech. | you'll
don't
it's
we're | +| Currency | Use the currency symbol first, followed by the amount. Where appropriate, round to a whole number. | I have two hundred dollars. | €300
$22,600
€22.6 million | +| Dates | Avoid expressing a month as a number to avoid common confusion around US/EU conventions. If there is no way around it, use the US-English “/” as separators for all content (such as marketing materials) with the exception of technical documentation (guides, manuals, etc.)
In technical documentation, use "-" as separators as it mirrors most timestamps in various programming languages. Also note that it may be best to remove the day of the week as it may not be as relevant as the day and month. | 10 December, 2018 | December 10, 2018 | +| Date ranges | Avoid repeating the same month twice in the same date range.
If you are using numerical values, enter as follows: Year, month, date. | Camunda Community Summit April 27 - April 28 | Camunda Community Summit April 27-28 | +| Genders | Our default is to optimize for gender neutral writing in most cases, unless a person has specified their pronouns in advance. | He/she | A group of people/a person: They
A business: It
A user: The user, they | +| [In to vs. into](https://www.grammarly.com/blog/into-vs-in-to/) | Always think of "into" as a single preposition (within or outside of something.)
Typically, "into" refers to physically going inside.
Think of "in to" as two independent prepositions that happen to end up next to one another, and typically aren't physically entering or exiting something.
Oftentimes, you can tell if you should use "in to" because you could place a comma after "in," and the sentence would still make sense. | Type your name in to the text box to sign up for Camunda 8.
"Check which folder the file is into ensure you are in the correct location." | Type your name into the text box to sign up for Camunda 8.
"Check which folder the file is in to ensure you are in the correct location." | +| Italics | Use when applying emphasis to a word. | Avoid overuse, using for button names.
Click _Create New Diagram_. | See the **Bolding** section in this style guide above.
Click **Create New Diagram** under the **Diagrams** tab.
"You _must_ ensure your environment is configured correctly before moving forward through the steps below." | +| Numbers | Write whole numbers one through nine in full.
Whole numbers 10 and upwards are written as numerals.
Large numbers may be written as numerals with definition (million, billion).
Currency does not follow the same rules. See details in the sub-section titled **Currency** above this table. | In this example, we will create 1 diagram and eleven processes to help 1,000,000 customers. | In this example, we will create one diagram and 11 processes to help 1 million customers. | +| Percentages | Written as % and always in numerals. | 10 percent | 10% | +| Pronoun references | Unclear pronoun reference occurs when a pronoun (often "it," "this," "that," or "they") could refer to more than one subject in a sentence, according to practice by [English Composition](https://englishcomposition.org/essential-writing/unclear-pronoun-reference/). Practice clarifying these pronouns, and removing them where appropriate. | After you execute `npm start`, you can run it.
In the example above, what exactly are we running? | After you execute `npm start`, you can run the program.
In the revised example above, we removed the unclear pronoun. | +| Spacing | Following a period, it is standard to have _one_ space before beginning a new sentence. | Avoid using two spaces after a period. | "Message correlation is a powerful feature in Camunda 8. It allows you to target a running workflow with a state update from an external system asynchronously." | +| Spelling | Default to American spelling and US English.
See details in the sub-section titled **Spelling** below this table. | Analyse
Colour
Capitalise
Humour
Bernd Rücker | Analyze
Color
Capitalize
Humor
Bernd Ruecker | +| Times | Use the 12-hour clock, preferably UTC, followed by a.m. and p.m. Always use the corresponding time zone when necessary.
See this useful list of [standard abbreviations](https://www.timeanddate.com/time/zones/) for time zones.
Be mindful of time zones when writing about events that occur across multiple borders.
Standardizing on time zones, we typically communicate in or default to CET/CEST, EST/EDT, and PST/PDT.
CET or CEST is used depending on daylight savings time, with CEST indicating Central European Summer Time.
EST/EDT and PST/PDT are used depending on daylight savings time, with EDT/PDT indicating daylight savings. | Avoid using hyphens to display time periods. Instead, use an en dash.
To type an en dash on your Mac, type Option+Minus (-).
To type an en dash on Windows, hold down Alt and type 0150 on the numeric keyboard; the en dash appears upon releasing the Alt key. | 1 p.m. CET
10 a.m. PST
6:30–10 a.m. EDT | +| Voice/Tense | Second person, [active voice](https://www.grammarly.com/blog/active-vs-passive-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. | +| Empowering language | Focus on what the feature or product empowers users to do. Prefer framing that centers the user and the outcome, such as “With ``, you can…” or “With ``, you’ll…”. | Framing features primarily in terms of what they allow or permit. | With multi-tenancy, you can isolate users, data, and workloads across tenants.
With Camunda agentic orchestration, you’ll orchestrate AI agents within your BPMN-based workflows. | +| Years | Don’t use an apostrophe for years. | 1960's | 1960s | ### Spelling @@ -73,14 +75,14 @@ We encourage document authors and technical writers to keep in mind grammar, pun Default to [American punctuation](https://www.unr.edu/writing-speaking-center/student-resources/writing-speaking-resources/british-american-english). | Subject | Practice | Avoid | Use | -| -------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | +| :------------------------------------------------------------------------------- | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | [Apostrophes](https://www.thepunctuationguide.com/apostrophe.html) | There are three key uses for apostrophes: contractions, plurals, and possessives.
Apostrophes are not used for time periods.
If the noun ends in an 's', place the apostrophe after the 's'. | 1980's
Let us run the command below.
We work to assist the businesses's microservices. | Let us = Let's
Do not = Don't
It is = It's
1980s
Let's run the command below.
We work to assist the businesses' microservices. | | [Commas](https://www.grammarly.com/blog/comma/) | Camunda uses the [Oxford comma](https://www.grammarly.com/blog/what-is-the-oxford-comma-and-why-do-people-care-so-much-about-it/). See details in the sub-section titled "Oxford comma" below this table.
Always use a comma to separate independent clauses when they are joined by any of these seven [coordinating conjunctions](https://www.grammarly.com/blog/coordinating-conjunctions/): and, but, for, or, nor, so, yet.
Avoid using too many commas and initiating a [run-on sentence](https://owl.purdue.edu/owl/general_writing/punctuation/independent_and_dependent_clauses/runonsentences.html), however. When possible, use short, separate sentences as opposed to several pieces of information in one sentence.
Always use a comma to separate a sentence introduction from the remainder of the sentence content (Therefore, Thus, As a result, So, Henceforth,)
In some specific cases, primarily on social media and where copy is exceptionally brief and clear, the Oxford comma is omitted. It should be used consistently in web and long-form content. | Camunda loves its products, GitHub and Google Analytics.
We want to automate a process so let's start by creating an account with Camunda 8.
Therefore we needed to wait for the program to load. | Camunda loves its products, GitHub, and Google Analytics.
We want to automate a process, so let's start by creating an account with Camunda 8.
Therefore, we needed to wait for the program to load. | | [Em dash](https://www.grammarly.com/blog/why-you-should-love-the-em-dash/) | —
As you can see, em dashes are slightly longer than en dashes.
On a Mac, execute Shift+Option+Minus (-); on Windows use Ctrl+Alt+Minus (-).
The em dash is used to set apart additional, descriptive notes also defined as "parenthetical information," or information you might put inside parentheses.
In many programs, you will be unable to create an em dash with a single line. In these instances, please use two hyphens (--) with no white space between to create an em dash.
If you find yourself pondering if you're using this correctly, cover up the sentence you've written after the em dash. If the first sentence makes perfect sense without it, then you're onto a winner. | - –
In the true spirit of the city Camunda was founded, Berlin, Germany, Camunda is a diverse, distributed and global organization with "Camundos" around the world.
At Camunda, we have made it our mission to enable organizations to design, automate and improve these processes, no matter where they are and what they entail.
Camunda was founded in 2008, at a time when established industry players were advocating a low-code approach, but we believed in a developer-first approach. | In the true spirit of the city Camunda was founded—that is, Berlin, Germany— Camunda is a diverse, distributed, and global organization with "Camundos" around the world.
At Camunda, we have made it our mission to enable organizations to design, automate and improve these processes—no matter where they are and what they entail.
Camunda was founded in 2008, at a time when established industry players were advocating a low-code approach—but we believed in a developer-first approach. | | [En dash](https://www.grammarly.com/blog/dash/) | –
The en dash is shorter than an em dash, and is not the same as a hyphen.
To type an en dash on your Mac, type Option+Minus (-). To type an en dash on Windows, hold down Alt and type 0150 on the numeric keyboard; the en dash will appear upon releasing the Alt key.
The en dash should predominantly be used for date and time ranges. | -
The scheduled window for the installation is 1-3pm. | The scheduled window for the installation is 1–3 p.m. | | Hyphens | Use the hyphen (-) to create a compound adjective (where you squash two describing words together, just like German, but easier to read.) | User friendly interface.
Biggest ever release. | User-friendly interface.
Biggest-ever release. | | [Prefixes](https://dictionary.cambridge.org/us/grammar/british-grammar/prefixes) | Prefixes are a stumbling block for many individuals with English as their first language. There's no right or wrong way to use them, because it genuinely depends on the dictionary you use, the style guide you follow, or just how confusing we want to make the language.
Prefixes are basically a few letters tagged at the front of a word to create a different meaning.
Ensure you omit the hyphen!
If at any point you feel a word doesn't look quite right, just send DevRel a quick Slack, because, unfortunately, there are a ton of exceptions. | Un happy
De activate
Re-activate
Un-do | Unhappy
Deactivate
Reactivate
Undo | -| Quotation marks | We only use double quotations to illustrate the words spoken by another individual.
We do not use quotations when referring to buttons or programs, nor sections of a document.
See the **Bolding** section in the table above. | One of the greatest benefits of this project has been the close cooperation between business and IT. -Michael Voeller, Head of Project and Demand Management
Navigate to the "**Decisions**" section of this manual. | "One of the greatest benefits of this project has been the close cooperation between business and IT," said Michael Voeller, Head of Project and Demand Management
Navigate to the **Decisions** section of this page.
Preferably, we would link the **Decisions** section in the example above so the user doesn't have to go out of their way to find it. | +| Quotation marks | We only use double quotations to illustrate the words spoken by another individual.
We do not use quotations when referring to buttons or programs, nor sections of a document.
Following AP Style, we use quotation marks for titles of books, articles, and similar works (see [AP Style guidance on quotation marks](https://x.com/APStylebook/status/1110901868350328833)).
See the **Bolding** section in the table above. | One of the greatest benefits of this project has been the close cooperation between business and IT. -Michael Voeller, Head of Project and Demand Management
Navigate to the "**Decisions**" section of this manual. | "One of the greatest benefits of this project has been the close cooperation between business and IT," said Michael Voeller, Head of Project and Demand Management.
Navigate to the **Decisions** section of this page. | | Semicolons | Semicolons are a wondrous use of punctuation when understood! Semicolons are stronger than a comma, but not as divisive as a period.
Use semicolons to connect two related but independent clauses (the two pieces of information are related to one another, but they can also stand alone.)
Do not capitalize the first word of the second clause following the semicolon unless it is a proper noun or acronym.
Semicolons are also used to replace conjunctions (and, or, etc.) | We've automated several processes for our partners, we love to see them succeed. | We've automated several processes for our partners; we love to see them succeed. | ### Oxford comma @@ -95,7 +97,7 @@ To help clarify this statement, we need to separate all of the subjects by a com **"Camunda loves its products, GitHub, and Google Analytics."** -- **Why it's preferred**: The Oxford comma is preferred because it erases potential confusion within a sentence or list. Take a look at the second example below: +- **Why it's preferred**: The Oxford comma is preferred because it erases potential confusion within a sentence or sentence list. Take a look at the second example below: **"Rachel Ray finds inspiration in cooking her family and her dog."** @@ -105,52 +107,53 @@ In the example above, one might assume Rachel Ray finds inspiration in cooking h ## Formatting, organization and structure for conceptual pieces The following table outlines best practices for conceptual pieces of information in the document. These pieces usually introduce the reader to a topic with a goal of teaching the reader about that topic before introducing further details or steps for implementation. (For example, an opening summary or overview of the document subject.) -| Subject | Practice| Avoid | Use | -| -- | -- | -- | -- | -| Concise writing | One of the most important techniques in technical writing is keeping your text short, clear, clean, and concise.
As a result, work to eliminate unnecessary words or phrases to reduce the amount of text the user must read.
To help test how readable and user-friendly your text is, review these [readability metrics](https://medium.com/technical-writing-is-easy/readability-metrics-and-technical-writing-b776422eaba) you can use.
Review this additional [guide to Hemingway](https://medium.com/technical-writing-is-easy/hemingway-app-for-technical-writing-f994c8b2412a), a great tool to test the readability and user experience of your document. | Camunda 8 is powered by Zeebe, a new class of BPMN workflow engine that delivers true horizontal scalability and enables high-performance use cases that were once beyond the realm of workflow automation.
Camunda 8 is architected for the cloud from the ground up. It is ideal for cloud application use cases such as microservices-based applications and integrates seamlessly with best-in-class cloud components. | Camunda 8 is powered by Zeebe, a new class of BPMN workflow engine that delivers horizontal scalability and high-performance use cases for workflow automation.
Ideal for microservice-based applications, Camunda 8 easily integrates with industry-leading cloud components. | -| Icons | -You may utilize `` and `` icons in the documentation for clarity. | N/A | N/A | -| Separated paragraphs | A user-friendly experience is a clean, concise one with as few words as possible.
A user-friendly experience separates these chunks of information into separate sections for easy reading and organization.
Avoid large, lengthy paragraphs. Instead, try to keep your paragraphs to a maximum of four or five sentences, and then begin a new paragraph introducing more information. | Message correlation is a powerful feature in Camunda 8. It allows you to target a running workflow with a state update from an external system asynchronously. This tutorial uses the Node.js client, but it serves to illustrate message correlation concepts that are applicable to all language clients. We will use Simple Monitor to inspect the running workflow state. Simple Monitor is a community-supported tool, and is not designed to be used in production - however, it is useful during development. | Message correlation is a powerful feature in Camunda 8. It allows you to target a running workflow with a state update from an external system asynchronously.
This tutorial uses the Node.js client, but it serves to illustrate message correlation concepts that are applicable to all language clients.
We will use Simple Monitor to inspect the running workflow state. Simple Monitor is a community-supported tool, and is not designed to be used in production - however, it is useful during development. | -| Short sentences | Avoid long, lengthy sentences and practice short, separate sentences when describing various processes and technologies. This will help the user take a step-by-step approach, piece by piece, through a larger conceptual item without getting lost or feeling overwhelmed. | At Camunda we have made it our mission to provide developers with the best experience because our platform and tools are easy to get started and use in your environment right away, with full public access to all our docs, open APIs to integrate with just about anything, and a vibrant community of 100,000 developers. | At Camunda we have made it our mission to provide developers with the best experience. Our platform and tools are easy to get started and use in your environment right away. We offer full public access to all our docs and open APIs. We strive to integrate with just about anything, and a vibrant community of 100,000 developers. | -| That | Avoid overuse of the term "that." More often than not, the term is repetitive or unnecessary.
To practice, double check your sentences by typing Ctrl+F and searching the term "that." Read your sentences without the term to see if the sentences still make sense. If they do, chances are you can remove the term.
Typically, you can remove "that" before most nouns, though you may want to keep "that" before an adjective. | To confirm that the first gateway works correctly, complete the steps below: | To confirm the first gateway works correctly, complete the steps below: | -| Titles, headers, and sidebars | Sentence case spelling in titles and headers.
For sentence case spelling, only capitalize the first word and any proper nouns.
Ensure titles and headers are descriptive enough so Camunda doesn't have a large surplus of mere "Overview" pages.
In Markdown, do not include a colon in your headers.
Note that for clean, short sidebar labels, you may remove excess wording that would usually align with the style guide. | How To Open A File
Our travel guide to berlin, germany
Camunda 8 overview
Readiness probe as yaml config:
Process instance modification | How to open a file
Our travel guide to Berlin, Germany
What is Camunda 8?
Readiness probe as yaml config
Modifying process instances | -| Whether or not | "Whether X produces the expected value or not" can seem a bit repetitive.
In most cases, it is appropriate to remove the "or not" at the end of the sentence to avoid repetition and unnecessary text.
In a picturesque world, we should lean on "If X produces the expected value," entirely eliminating the need to use the "whether or not" terminology. | This specifies whether host language resources like classes and their methods are accessible or not. | This specifies if host language resources like classes and their methods are accessible. | + +| Subject | Practice | Avoid | Use | +| :---------------------------- | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| Concise writing | One of the most important techniques in technical writing is keeping your text short, clear, clean, and concise.
As a result, work to eliminate unnecessary words or phrases to reduce the amount of text the user must read.
To help test how readable and user-friendly your text is, review these [readability metrics](https://medium.com/technical-writing-is-easy/readability-metrics-and-technical-writing-b776422eaba) you can use.
Review this additional [guide to Hemingway](https://medium.com/technical-writing-is-easy/hemingway-app-for-technical-writing-f994c8b2412a), a great tool to test the readability and user experience of your document. | Camunda 8 is powered by Zeebe, a new class of BPMN workflow engine that delivers true horizontal scalability and enables high-performance use cases that were once beyond the realm of workflow automation.
Camunda 8 is architected for the cloud from the ground up. It is ideal for cloud application use cases such as microservices-based applications and integrates seamlessly with best-in-class cloud components. | Camunda 8 is powered by Zeebe, a new class of BPMN workflow engine that delivers horizontal scalability and high-performance use cases for workflow automation.
Ideal for microservice-based applications, Camunda 8 easily integrates with industry-leading cloud components. | +| Icons | You may utilize `` and `` icons in the documentation for clarity. | N/A | N/A | +| Separated paragraphs | A user-friendly experience is a clean, concise one with as few words as possible.
A user-friendly experience separates these chunks of information into separate sections for easy reading and organization.
Avoid large, lengthy paragraphs. Instead, try to keep your paragraphs to a maximum of four or five sentences, and then begin a new paragraph introducing more information. | Message correlation is a powerful feature in Camunda 8. It allows you to target a running workflow with a state update from an external system asynchronously. This tutorial uses the Node.js client, but it serves to illustrate message correlation concepts that are applicable to all language clients. We will use Simple Monitor to inspect the running workflow state. Simple Monitor is a community-supported tool, and is not designed to be used in production - however, it is useful during development. | Message correlation is a powerful feature in Camunda 8. It allows you to target a running workflow with a state update from an external system asynchronously.
This tutorial uses the Node.js client, but it serves to illustrate message correlation concepts that are applicable to all language clients.
We will use Simple Monitor to inspect the running workflow state. Simple Monitor is a community-supported tool, and is not designed to be used in production - however, it is useful during development. | +| Short sentences | Avoid long, lengthy sentences and practice short, separate sentences when describing various processes and technologies. This will help the user take a step-by-step approach, piece by piece, through a larger conceptual item without getting lost or feeling overwhelmed. | At Camunda we have made it our mission to provide developers with the best experience because our platform and tools are easy to get started and use in your environment right away, with full public access to all our docs, open APIs to integrate with just about anything, and a vibrant community of 100,000 developers. | At Camunda we have made it our mission to provide developers with the best experience. Our platform and tools are easy to get started and use in your environment right away. We offer full public access to all our docs and open APIs. We strive to integrate with just about anything, and a vibrant community of 100,000 developers. | +| That | Avoid overuse of the term "that." More often than not, the term is repetitive or unnecessary.
To practice, double check your sentences by typing Ctrl+F and searching the term "that." Read your sentences without the term to see if the sentences still make sense. If they do, chances are you can remove the term.
Typically, you can remove "that" before most nouns, though you may want to keep "that" before an adjective. | To confirm that the first gateway works correctly, complete the steps below: | To confirm the first gateway works correctly, complete the steps below: | +| Titles, headers, and sidebars | Sentence case spelling in titles and headers.
For sentence case spelling, only capitalize the first word and any proper nouns.
Ensure titles and headers are descriptive enough so Camunda doesn’t have a large surplus of mere “Overview” pages.
Additionally, ensure titles and headers are action items.
In Markdown, do not include a colon in your headers.
Note that for clean, short sidebar labels, you may remove excess wording that would usually align with the style guide.
For blog content, use sentence case for headers within the body of the post, but Title Case for the titles themselves. | How To Open A File
Our travel guide to berlin, germany
Camunda 8 overview
Readiness probe as yaml config:
Process instance modification | How to open a file
Our travel guide to Berlin, Germany
What is Camunda 8?
Readiness probe as yaml config
Modifying process instances | +| Whether or not | "Whether X produces the expected value or not" can seem a bit repetitive.
In most cases, it is appropriate to remove the "or not" at the end of the sentence to avoid repetition and unnecessary text.
In a picturesque world, we should lean on "If X produces the expected value," entirely eliminating the need to use the "whether or not" terminology. | This specifies whether host language resources like classes and their methods are accessible or not. | This specifies if host language resources like classes and their methods are accessible. | ### Titles and headers (sentence case): - **Why we use it**: Camunda uses sentence case spelling in titles and headers within technical documentation because this format is more synchronous with the way and flow of human speaking and writing, allowing a more modern and user-friendly approach to the document. - **Why it's preferred**: On top of its modern structure, sentence case titles and headers tend to read more clear, clean, and neat on the page. While title case is great for printed newspapers and magazines, sentence case tends to read more friendly on the web in a conversational style. See a few of our examples below: - **"Setting up your first development project"** - **"Monitor your process in Operate"** - **"Getting started with Camunda 8"** + **"Setting up your first development project"** **"Monitor your process in Operate"** **"Getting started with Camunda 8"** ## Formatting, organization and structure for implementation steps The following table outlines best practices for the implementation section of the document. This section usually offers a distinct thing or things for the reader to do (for example, a list of steps). -| Subject | Practice | Avoid | Use | -| ----------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| [Admonitions](https://docusaurus.io/docs/markdown-features/admonitions) | Currently within Docusaurus, we have the opportunity to utilize [admonitions](https://docusaurus.io/docs/markdown-features/admonitions) to separate important notes in our documents. Please utilize these admonitions appropriately according to [Docusaurus' guidance](https://docusaurus.io/docs/markdown-features/admonitions). This will add a significant boost to our UX! | 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 | -| Bulleted lists | Use bulleted lists for a list of three or more items.
You may use complete sentences in bulleted lists (followed by a period), or you may avoid using periods in your bulleted lists if the items are fragmented or short (apples, bananas, grapes, for example).
Always capitalize the first word of the item in the bullet. | Do not use bullets for a series of steps or instructions. Instead, use numerical lists. See **Numerical lists/steps** in the table below.
Avoid using commas and/or semicolons in bulleted lists as this can cause confusion between listed items.
Do not lowercase the first word following each bullet. Ensure capitalization. | Camunda 8 can be used for several purposes, including:
    • To automate a process

      To avoid bottlenecks in business
      To create an organized framework
    • | -| Button names | Click **Next**.
    Use the arrow icon > to list out a series of buttons the user needs to press.
    See **Menu bar traversal** for details in the table below. | Italics and quotes.
    Click "Next" and then select "Open" and press "Enter" at the bottom of the page. | Verb + **Button Name**
    Can use screenshot or icon in instructions.
    Click **Next** > **Open** > **Enter** | -| Button verbs | Use common terms like **Click** or **Select**. | Hit, press
    Hit the **Next** button. | Click, select
    Select **Next**. | -| Code blocks | Use code blocks when you are specifically referring to components within code or filenames.
    Use code block highlighting, if available. This will not apply to inline code, but instead for larger blocks of code. | Do not use code blocks for anything outside of code or filenames, including buttons, titles, etc. | Ensure the `taskID` on your JavaScript page is the same.
    Execute the following command:
    `npm start`
    `javascript var = 1;` | -| Filenames | Place filenames within a code block, as noted in the component **Code blocks** in the table above. | Avoid bolding or italicizing filenames. | Open `codeStuff.txt` | -| Gifs | Gifs are strongly discouraged in place of text for maintainability and accessibility purposes.
    If possible, refrain from implementing these in documentation. If you must include them, ensure sufficient text outlines what it taking place in the gif for accessibility purposes. | N/A | N/A | -| Images | Ensure your images are appropriate in size and clarity.
    All images should include alt text for accessibility purposes.
    If using a screenshot to show steps to fill out a UI, include text above or below the screenshot that includes input text.
    Crop the user bar and any personal information out of your photo or screenshot. This may include names, passwords, usernames, etc. | Avoid blurry screenshots. Avoid including any personal information in your images. If you must use a username, use "My organization". Avoid images that are unnecessarily large or bulky to keep the page clean and concise. | N/A | -| Latin abbreviations | Do not use Latin abbreviations. Instead, use "for example." | e.g. or i.e. | For example, | -| Links | Link text whenever it refers to a separate section of our documentation or website. No section reference should go unlinked.
    Ensure links are externally linked, meaning when clicked, the link will open in a separate tab and not remove the position the user is in within the documentation in their current tab.
    Please also make sure any repo links are linked to the anchor link on the repo instead of the main/`{branch name}` link.
    Links should use descriptive wording, rather than just "click here".
    Deep link to specific sections of a document where appropriate. | Visit our Getting Started Guide for more details.
    Click here for more details.
    Learn more about...
    To read more...
    "For more information, see the `[deploying](LINK)` page." | Visit [Get started with Camunda](https://docs.camunda.org/get-started/) for more details.
    To learn more about migrating from Camunda 7 to Camunda 8, visit our migration guide.
    To (do X), visit `[X](LINK)`.
    For more information, see `[merge request](LINK)`. | -| Menu bar traversal | When listing out a series of buttons as steps, use the arrow key to break between buttons. | In the "File" menu, click "Save as." | In the **File** menu, click **Save as**.
    Go to **File > New File > BPMN Diagram**. | -| Notes | When using an admonition to create a note (see the row titled **Admonitions** above) do not place several notes in a row.
    Either remove the information in the sequential notes and leave them as paragraphs/independent sentences, or spread the notes out directly alongside the content the note is referring to. | Admonition, with another admonition immediately following it. | “According to XYZ, it’s important to note...
    Additionally, note that...” | -| Numerical lists/steps | When possible, replace a loaded or long sentence with a series of steps to keep things clear and concise.
    See details in the sub-section titled **Numerical lists/steps** below this table. | Use the Camunda Modeler to open the Payment Retrieval process then click on the Approve Payment Task. Change the activity type to Business Rule Task in the wrench button menu. | 1. Use Camunda Modeler to open the **Payment Retrieval** process.
    2. Click the **Approve Payment** task.
    3. Click the wrench icon, revealing a menu, to change the **activity type** to **Business Rule Task**. | -| Optional steps | Steps may be listed as optional where appropriate. | `1. Optional. Check this out.` | `(Optional) Check this out.` | -| Unordered lists | Do not use numerical lists for lists of items without a set order of actions.
    Additionally, use dashes (minus) instead of asterisks (star). | You can do the following with Optimize: `1. Create reports 2. Create dashboards 3. Analyze heat maps` | You can do the following with Optimize: `- Create reports - Create dashboards - Analyze heatmaps` | -| Please and thank you | In technical writing, give direct, clear instructions. You do not need to ask the user to "please" do something.
    Do not use "please" in a numerical or bulleted list.
    This may seem rather blunt, but our goal is to create clean, direct instructions and documentation. | Please open the link. | Open the link. | -| Semantic versioning | **X** is used when applying a topic to all subsequent patch releases since the minor release.
    0 or another number representing a specific patch release (8, 9, etc.) means you are specifying the minor release, or a particular patch release.
    **+**, therefore, should only be used alongside a specific number specifying a release, and should not follow an X. | Check out the feature in version 8.4.x+. | This feature is available with 8.4.10+. | -| Tabs | When listing several different command options across operating systems, ensure these different references are separated into their own tabs for a clean, clear UX. | See this [documentation](https://docs.camunda.io/docs/components/concepts/process-instance-creation/) example. | See this [GitHub](https://github.com/camunda-cloud/camunda-cloud-documentation/pull/345) example. | -| Visuals | Keep visuals in mind as you create a document to avoid large, lengthy paragraphs. Consider the following:
    Would this series of information be more visually-appealing in a table?
    Should I add a brief video, gif, or image to show the user the more complex steps I've described? | Avoid several paragraphs of information contained in large bodies of text. | Practice clean, clear, and brief chunks of text. Consider a table or image to display the information you've outlined. | +| Subject | Practice | Avoid | Use | +| :-------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| Admonitions | Write information inline by default, especially if it’s required for user success.
    Readers often skip notices, so use admonitions only when information would be easy to miss while skimming or when it materially changes user behavior or risk.
    Limit the number of admonitions per page and avoid grouping multiple admonitions together.
    To keep usage consistent, limit admonitions to a small, opinionated set: **Warning**, **Note**, and **Tip** (optional). | Using admonitions for prerequisites or required setup.
    Introducing too many admonition types.
    Placing core steps or required actions inside admonitions.
    Stacking multiple admonitions in a row.
    Using admonitions where inline text would be clearer.
    Using admonitions for in-text references to other docs. | **Warning** – Use for actions that can cause serious or irreversible harm (data loss, security exposure, major system impact).
    `:::warning`
    Deleting the cluster permanently removes all workflow data and cannot be undone.
    `:::`

    **Note** – Use for optional, non-critical context that’s helpful but not required for success.
    `:::note`
    This setting applies only to newly created clusters. Existing clusters are not affected.
    `:::`

    **Tip** (optional) – Use for optional guidance that helps users be more effective or efficient. | +| 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 | +| Bulleted lists | Use bulleted lists for a list of three or more items.
    You may use complete sentences in bulleted lists (followed by a period), or you may avoid using periods in your bulleted lists if the items are fragmented or short (apples, bananas, grapes, for example).
    Always capitalize the first word of the item in the bullet. | Do not use bullets for a series of steps or instructions. Instead, use numerical lists. See **Numerical lists/steps** in the table below.
    Avoid using commas and/or semicolons in bulleted lists as this can cause confusion between listed items.
    Do not lowercase the first word following each bullet. Ensure capitalization. | Camunda 8 can be used for several purposes, including:
    • To automate a process

      To avoid bottlenecks in business
      To create an organized framework
    • | +| Button names | Click **Next**.
    Use the arrow icon > to list out a series of buttons the user needs to press.
    See **Menu bar traversal** for details in the table below. | Italics and quotes.
    Click "Next" and then select "Open" and press "Enter" at the bottom of the page. | Verb + **Button Name**
    Can use screenshot or icon in instructions.
    Click **Next** > **Open** > **Enter** | +| Button verbs | Use common terms like **Click** or **Select**. | Hit, press
    Hit the **Next** button. | Click, select
    Select **Next**. | +| CLI commands | Use CLI commands cautiously. Do not assume users have command-line tools installed unless the documentation explicitly instructs them to install and use those tools. | Using CLI commands without explaining required tooling or installation steps. | Explicitly guide users through installing and using required CLI tools before referencing commands. | +| Code blocks | Use code blocks when you are specifically referring to components within code or filenames.
    Use code block highlighting, if available. This will not apply to inline code, but instead for larger blocks of code. | Do not use code blocks for anything outside of code or filenames, including buttons, titles, etc. | Ensure the `taskID` on your JavaScript page is the same.
    Execute the following command:
    `npm start`
    `javascript var = 1;` | +| Details elements | You may use `
    ` elements to hide or collapse optional content such as reference material or code examples. | Placing required steps or critical information inside `
    ` elements. | Use `
    ` only for optional or supplementary information. | +| Filenames | Place filenames within a code block, as noted in the component **Code blocks** in the table above. | Avoid bolding or italicizing filenames. | Open `codeStuff.txt` | +| Gifs | Gifs are strongly discouraged in place of text for maintainability and accessibility purposes.
    If possible, refrain from implementing these in documentation. If you must include them, ensure sufficient text outlines what it taking place in the gif for accessibility purposes. | N/A | N/A | +| Images | Ensure your images are appropriate in size and clarity.
    All images should include alt text for accessibility purposes.
    If using a screenshot to show steps to fill out a UI, include text above or below the screenshot that includes input text.
    Crop the user bar and any personal information out of your photo or screenshot. This may include names, passwords, usernames, etc. | Avoid blurry screenshots. Avoid including any personal information in your images. If you must use a username, use "My organization". Avoid images that are unnecessarily large or bulky to keep the page clean and concise. | N/A | +| Latin abbreviations | Do not use Latin abbreviations. Instead, use "for example." | e.g. or i.e. | For example, | +| Links | Link text whenever it refers to a separate section of documentation or an external website. **Section references must always be links.**
    Link directly to the most relevant **section** of a page, rather than the top of the page, to reduce cognitive load and avoid forcing users to scan for information.
    Ensure external links open in a separate tab so users do not lose their place in the documentation.
    Use descriptive link text instead of generic phrases like “click here.”
    Avoid `/docs/file/example.md`, which routes users to the `/next/` documentation; use `/file/example.md` instead.
    When linking to repositories, link to the relevant anchor instead of the repository root or a branch (`main`, `master`).
    Whenever possible, use existing sentence text as the link.
    Only use “Learn more about …” (preferred) or “Learn more” when unavoidable due to space constraints.
    UI text links may be short phrases and do not need to be full sentences; this exception does not apply to documentation prose.
    Underline links when they appear inline in paragraphs. Do not show a launch icon. | Click here for more details.
    Learn more about…
    To read more…
    “For more information, see the `[deploying](LINK)` page.”
    Linking only to the top of a long page when a specific section is relevant.
    `/docs/file/example.md` | Visit [Get started with Camunda](https://docs.camunda.io/get-started/){:target="\_blank"} for more details.
    To configure authentication, see [Authentication configuration](LINK#authentication-configuration).
    For more information, see the [merge request](LINK).
    `/file/example.md` | +| Menu bar traversal | When listing out a series of buttons as steps, use the arrow key to break between buttons. | In the "File" menu, click "Save as." | In the **File** menu, click **Save as**.
    Go to **File > New File > BPMN Diagram**. | +| Notes | When using an admonition to create a note (see the row titled **Admonitions** above) do not place several notes in a row.
    Either remove the information in the sequential notes and leave them as paragraphs/independent sentences, or spread the notes out directly alongside the content the note is referring to. | Admonition, with another admonition immediately following it. | “According to XYZ, it’s important to note...
    Additionally, note that...” | +| Numerical lists/steps | When possible, replace a loaded or long sentence with a series of steps to keep things clear and concise.
    See details in the sub-section titled **Numerical lists/steps** below this table.
    When referring to steps retroactively, bold and capitalize. | Use the Camunda Modeler to open the Payment Retrieval process then click on the Approve Payment Task. Change the activity type to Business Rule Task in the wrench button menu.
    Save the credentials created in step 1. | 1. Use Camunda Modeler to open the **Payment Retrieval** process.
    2. Click the **Approve Payment** task.
    3. Click the wrench icon to change the activity type to **Business Rule Task**.
       Save the credentials created in **Step 1**. | +| Optional steps | Steps may be listed as optional where appropriate. | `1. Optional. Check this out.` | `(Optional) Check this out.` | +| Ordered lists | You may use `1.` for every item in an ordered list. Markdown renders the correct sequence automatically and this reduces renumbering errors. | Manually renumbering long ordered lists. | 4. Do this task
    5. Do the next task | +| Unordered lists | Do not use numerical lists for lists of items without a set order of actions.
    Additionally, use dashes (minus) instead of asterisks (star). | You can do the following with Optimize: `1. Create reports 2. Create dashboards 3. Analyze heat maps` | You can do the following with Optimize: `- Create reports - Create dashboards - Analyze heatmaps` | +| Please and thank you | In technical writing, give direct, clear instructions. You do not need to ask the user to "please" do something.
    Do not use "please" in a numerical or bulleted list.
    This may seem rather blunt, but our goal is to create clean, direct instructions and documentation. | Please open the link. | Open the link. | +| Semantic versioning | **X** is used when applying a topic to all subsequent patch releases since the minor release.
    0 or another number representing a specific patch release (8, 9, etc.) means you are specifying the minor release, or a particular patch release.
    **+**, therefore, should only be used alongside a specific number specifying a release, and should not follow an X. | Check out the feature in version 8.4.x+. | This feature is available with 8.4.10+. | +| Tabs | When listing several different command options across operating systems, ensure these different references are separated into their own tabs for a clean, clear UX. | See this [documentation](https://docs.camunda.io/docs/components/concepts/process-instance-creation/) example. | See this [GitHub](https://github.com/camunda-cloud/camunda-cloud-documentation/pull/345) example. | +| Visuals | Keep visuals in mind as you create a document to avoid large, lengthy paragraphs. Consider the following:
    Would this series of information be more visually-appealing in a table?
    Should I add a brief video, gif, or image to show the user the more complex steps I've described? | Avoid several paragraphs of information contained in large bodies of text. | Practice clean, clear, and brief chunks of text. Consider a table or image to display the information you've outlined. | ### Numerical lists/steps: @@ -171,7 +174,7 @@ On the first page of the New Maven Project Wizard, select Create a simple projec **To this**: -Create a new Maven project +Create a new Maven project Create a new Maven project in your IDE. If you're using Eclipse, follow these steps: 1. In Eclipse, go to **File > New > Other**. This opens the New Project Wizard. @@ -182,14 +185,17 @@ Create a new Maven project in your IDE. If you're using Eclipse, follow these st **NOTE: To avoid overuse of company jargon or confusion, please refer to [this summary of OMG specifications](https://www.omg.org/spec/category/business-modeling/) when referring to acronyms within your documentation.** -| Subject | Practice | Avoid | Use | -| ------------------------------------------------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| Acronyms | BPMN, DMN, TTFN – the use of acronyms should be judged by the level of audience knowledge.
    For a technical audience, use industry standard acronyms from the start. However, for new concepts or emerging acronyms, write the process in full first, and then follow with the acronym at the next use.
    For a non-technical audience, always write an acronym in full the first time you use it in any new piece of content. Afterwards, it can be abbreviated. | Avoid abbreviating the term on its first use if the documentation is for an audience which may be non-technical. | Most often, you should spell out the acronym on first reference and abbreviate thereafter depending on the level of audience knowledge. | -| And/or | Either or both of two stated possibilities. | You can further parallelize archiver and(or) importer within one node using the following configuration parameters | You can further parallelize archiver and/or importer within one node using the following configuration parameters | -| File extensions | Do not capitalize file extensions like .pdf, .doc, etc. | Uppercase | Lowercase | -| [Job and professional titles](https://grammar.yourdictionary.com/capitalization/capitalization-of-job-titles.html) | Do not capitalize a job title if listed after a name.
    Do capitalize a job title if listed before a name.
    An exception may be within a list of people, such as a conference speakers list, where capitalizing titles may be appropriate. | Charley Mann, Content Strategist | Charley Mann, content strategist | -| Process | See details in the sub-section titled **Process vs. workflow** below this table. | Avoid "workflow automation" and "workflow instance" where "process automation" and "process instance" is preferred. | We prefer process automation and process instance over workflow automation or workflow instance.
    See details in the sub-section titled **Process vs. workflow** below this table. | -| Workflow | See details in the sub-section titled **Process vs. workflow** below this table. | Avoid "workflow automation" and "workflow instance" where "process automation" and "process instance" is preferred. | We prefer process automation and process instance over workflow automation or workflow instance.
    See details in the sub-section titled **Process vs. workflow** below this table. | +| Subject | Practice | Avoid | Use | +| :--------------------------- | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :------------------------------------------------------------------------------------------------------------------ | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | +| Acronyms | BPMN, DMN, TTFN – the use of acronyms should be judged by the level of audience knowledge.
    For a technical audience, use industry standard acronyms from the start. However, for new concepts or emerging acronyms, write the process in full first, and then follow with the acronym at the next use.
    For a non-technical audience, always write an acronym in full the first time you use it in any new piece of content. Afterwards, it can be abbreviated. | Avoid abbreviating the term on its first use if the documentation is for an audience which may be non-technical. | Most often, you should spell out the acronym on first reference and abbreviate thereafter depending on the level of audience knowledge. | +| And/or | Either or both of two stated possibilities. | You can further parallelize archiver and(or) importer within one node using the following configuration parameters | You can further parallelize archiver and/or importer within one node using the following configuration parameters | +| File extensions | Do not capitalize file extensions like .pdf, .doc, etc. | Uppercase | Lowercase | +| Job and professional titles | In long-form copy, including news releases, do not capitalize a job title if listed after a name.
    Capitalize a job title if listed before a name.
    An exception may apply within a list of people, such as on Camunda’s [leadership page](https://camunda.com/about/leadership/) or a conference speakers list, where capitalizing titles may be appropriate.
    Always capitalize Camunda-specific roles (for example, Member, Owner). | Charley Mann, Content Strategist | Charley Mann, content strategist | +| Process | See details in the sub-section titled **Process vs. workflow** below this table. | Avoid "workflow automation" and "workflow instance" where "process automation" and "process instance" is preferred. | We prefer process automation and process instance over workflow automation or workflow instance.
    See details in the sub-section titled **Process vs. workflow** below this table. | +| Workflow | See details in the sub-section titled **Process vs. workflow** below this table. | Avoid "workflow automation" and "workflow instance" where "process automation" and "process instance" is preferred. | We prefer process automation and process instance over workflow automation or workflow instance.
    See details in the sub-section titled **Process vs. workflow** below this table. | +| BPMN sub-process terminology | Follow the spelling used by the product and BPMN specification when referring to BPMN concepts in running text. Use “sub-process” (hyphenated) in user-facing documentation. | Using “subprocess” or inconsistent variants when referring to BPMN concepts in prose. | sub-process
    event sub-process
    embedded sub-process
    ad-hoc sub-process | + +**Exception (technical contexts only):** Use `subProcess`, `AdHocSubProcess`, or `subprocess` only when directly quoting BPMN XML, code, APIs, or technical identifiers. ### Process vs. workflow: