diff --git a/howtos/technical-writing-cheatsheet.md b/howtos/technical-writing-cheatsheet.md index 26d6ff1da4..12174562ea 100644 --- a/howtos/technical-writing-cheatsheet.md +++ b/howtos/technical-writing-cheatsheet.md @@ -1,8 +1,8 @@ -# Tech Writing Cheat Sheet +# Camunda style guide cheat sheet ## Overview -A quickstart to the complete [Camunda Writing Style Guide](./technical-writing-styleguide.md). 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. +A quickstart to the complete [Camunda style guide](./technical-writing-styleguide.md). 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 @@ -28,23 +28,22 @@ Our primary goal in documentation is to achieve organization, clarity, and direc ## Formatting, organization and structure for conceptual pieces and implementation steps -| Subject | Practice | Avoid | Example/Use | -| ----------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------ | -| [Admonitions](https://docusaurus.io/docs/markdown-features/admonitions) | Utilize the note [admonition](https://docusaurus.io/docs/markdown-features/admonitions) to separate important notes in documents according to [Docusaurus’ guidance](https://docusaurus.io/docs/markdown-features/admonitions). | 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 | +| Subject | Practice | Avoid | Example/Use | +| ----------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------ | +| [Admonitions](https://docusaurus.io/docs/markdown-features/admonitions) | Utilize the note [admonition](https://docusaurus.io/docs/markdown-features/admonitions) to separate important notes in documents according to [Docusaurus’ guidance](https://docusaurus.io/docs/markdown-features/admonitions). | 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](https://www.omg.org/spec/category/business-modeling/) when referring to acronyms within your documentation.** -| Term/Acronym | Meaning | Avoid | Use | -| --------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------- | -| [Cluster](https://docs.camunda.io/docs/product-manuals/zeebe/technical-concepts/clustering) | 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](https://github.com/camunda-community-hub/camunda-bpm-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](https://docs.camunda.org/manual/7.15/reference/rest/task/get-query/#query-parameters) | 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](https://docs.camunda.org/manual/7.15/reference/rest/task/get-query/#query-parameters) | 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 | +| Term/Acronym | Meaning | Avoid | Use | +| ------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------ | ----------------------------------------------------------------------------------------------- | +| [Cluster](https://docs.camunda.io/docs/product-manuals/zeebe/technical-concepts/clustering) | 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](https://github.com/camunda-community-hub/camunda-bpm-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 | diff --git a/howtos/technical-writing-styleguide.md b/howtos/technical-writing-styleguide.md index 97f555be03..c36ef8f668 100644 --- a/howtos/technical-writing-styleguide.md +++ b/howtos/technical-writing-styleguide.md @@ -1,4 +1,4 @@ -# Camunda Style Guide +# Camunda style guide ## Overview @@ -53,6 +53,7 @@ We encourage document authors and technical writers to keep in mind grammar, pun | 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 | ### Spelling @@ -107,10 +108,12 @@ The following table outlines best practices for conceptual pieces of information | 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 and headers | 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. | How To Open A File
Our travel guide to berlin, germany
Camunda 8 overview
Readiness probe as yaml config: | How to open a file
Our travel guide to Berlin, Germany
What is Camunda 8?
Readiness probe as yaml config | +| 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. | ### Titles and headers (sentence case): @@ -126,21 +129,28 @@ The following table outlines best practices for conceptual pieces of information 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.
::: | -| 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` | -| 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. Avoid images that are unnecessarily large or bulky to keep the page clean and concise. | N/A | -| 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. | Visit our Getting Started Guide for more details. | Visit [Get started with Camunda](https://docs.camunda.org/get-started/) for more details. | -| 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**. | -| 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**. | -| 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. | -| 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/zeebe/deployment-guide/getting-started/create-process-instance/) 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](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. 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/zeebe/deployment-guide/getting-started/create-process-instance/) 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: