Skip to content

Commit

Permalink
Refresh style guide (#3742)
Browse files Browse the repository at this point in the history 
* update style guide

* update cheat sheet

* update casing
  • Loading branch information
@christinaausley
christinaausley authored Apr 30, 2024
1 parent 31688d5 commit 3c20eac
Show file tree
Hide file tree
Showing 2 changed files with 43 additions and 34 deletions.
33 changes: 16 additions & 17 deletions howtos/technical-writing-cheatsheet.md
View file
Original file line number Diff line number Diff line change
@@ -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

Expand All @@ -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<br>This is the `bpmnProcessId`, you'll need to create a new instance.<br>::: |
| Button names | Click **Next**.<br><br>Use the arrow icon > to list out a series of buttons the user needs to press. | Italics and quotes.<br><br>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`<br>In the **Name** box enter `project1`. |
| Images | Ensure your images are appropriate in size and clarity.<br>All images should include alt text.<br>Crop the user bar and any personal information out of your photo or screenshot. | Avoid blurry screenshots.<br>Avoid including any personal information in your images.<br>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.<br><br>For sentence case spelling, only capitalize the first word and any proper nouns. | How To Open A File<br><br>Our travel guide to berlin, germany | How to open a file<br><br>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<br>This is the `bpmnProcessId`, you'll need to create a new instance.<br>::: |
| 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**.<br><br>Use the arrow icon > to list out a series of buttons the user needs to press. | Italics and quotes.<br><br>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`<br>In the **Name** box enter `project1`. |
| Images and gifs | Ensure your images are appropriate in size and clarity.<br>All images should include alt text.<br>Crop the user bar and any personal information out of your photo or screenshot.<br>Gifs are strongly discouraged in place of text for maintainability and accessibility purposes. | Avoid blurry screenshots.<br>Avoid including any personal information in your images.<br>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.<br><br>For sentence case spelling, only capitalize the first word and any proper nouns. | How To Open A File<br><br>Our travel guide to berlin, germany | How to open a file<br><br>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.<br><br>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.<br><br>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.<br><br>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.<br><br>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 |
Loading

0 comments on commit 3c20eac

Please sign in to comment.