Skip to content

Commit

Permalink
add to howtos
Browse files Browse the repository at this point in the history
  • Loading branch information
@christinaausley
christinaausley committed Nov 27, 2024
1 parent 3a33715 commit ba66c85
Show file tree
Hide file tree
Showing 3 changed files with 13 additions and 9 deletions.
4 changes: 4 additions & 0 deletions howtos/documentation-guidelines.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -167,6 +167,10 @@ In an effort to automate screenshots across Camunda 8 documentation, the followi
Given the following procedures, teams will respond to screenshot updates and suggestions from community members by manually adjusting appropriate screenshots.
:::

:::note
When generating screenshots, remove any personal identifiable information. If a username must be included, ensure this is "My organization".
:::

**Modeler**
Visit the [Modeler screenshot automation repo](https://github.com/camunda/camunda-docs-modeler-screenshots/blob/main/README.md) for details on updating screenshots and scripting new screenshots.

Expand Down
16 changes: 8 additions & 8 deletions howtos/technical-writing-cheatsheet.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -28,14 +28,14 @@ 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>::: |
| 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 |
| 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. If a username must be included, use "My organization".<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

Expand Down
Loading

0 comments on commit ba66c85

Please sign in to comment.