All changes must be done in a separate branch. As soon as the changes are done please open a PR. A Github Action runs with every commit to a branch and checks if the documentation can be built (including a broken links check).
PRs should be in draft status while being actively worked or have a clear written status in the description or comment. Removing a PR from draft status indicates that it is ready for review (by a technical writer).
PRs should be labeled to help the Documentation Team quickly triage, review, and merge PRs according to urgency and priority.
Labels include identifiers for teams/components, minor and alpha releases, support engagements, etc. When opening a PR or issue, do your best to use labels that communicate the component, version, and or priority.
PRs can be labeled “hold” for any reason, including ongoing conversations, coordination across teams or departments, or anything that’s not obvious within the discussion or description of the PR.
PRs and issues without labels may be at risk for slow triage.
Adding a deploy label to a PR will trigger its deployment to a preview site, which will be linked in the PR description. We recommend using the deploy label for large or complex docs changes.
In the spirit of "Always Progress," if you are confident you know what change needs to be made, a separate issue on the topic is not required. However, if you have an idea that needs to go into the backlog, creating an issue instead of a PR is the best way to go.
- Name markdown files according to the title. This makes it easier to find a file. Example: Introduction to Camunda 8 -->
introduction-to-camunda-8.md. Avoid non-alphanumeric characters in titles. Use the file name as an internal document ID to reference in the appropriate sidebars file. - Subcategories have to be placed in their own sub-directories. Example:
Guides>Get started with Springcan be found in/guides/getting-started-java-spring.md.
Different versions are sourced from different paths:
| Instance | Version(s) | Source path |
|---|---|---|
docs |
Next | /docs/ |
docs |
8.7, 8.6, 8.5, ... | /versioned_docs/version-*/ |
When edits are intended to apply to both the current version and beyond, they should be made in both the most recent versioned folder and the "Next" version folder.
There is a separate source spec for each version of each API Explorer. Each API's source spec lives in the /api/ root folder, in a folder named for the API. Next versions of the spec live in the root of that folder; older versions of the spec live in child folders named by version number.
Sidebar navigation of the documentation is managed in the sidebars files. Each version of the documentation has its own sidebars file:
| Instance | Version(s) | Sidebars path |
|---|---|---|
docs |
Next | /docs/sidebars.js |
docs |
8.7, 8.6, 8.5, ... | /versioned_sidebars/version-*-sidebars.json |
JavaScript is a better format for a sidebars file, because it allows us to import sub-trees from a file defined somewhere else; however Docusaurus only supports a JSON sidebars file for the "next" version of the docs. Numbered versions of the docs are required to be JSON rather than JavaScript.
As such, when a new version is cut, it results in unused sidebar sub-tree .js files scattered throughout the codebase. Be aware that these exist, to avoid attempting to change a sidebars file that has no effect.
When linking internally from one document to another, follow these guidelines:
- Use a relative path to the target markdown file if it is in the same subtree as the source file. See example.
- Use an absolute path to the target markdown file if it is in a different subtree than the source file. See example.
- Refrain from using
/docs/<version>when using an absolute path. For example, use/components/components-overview.mdrather than/docs/components/components-overview.md. The latter will force Docusaurus to link to the vNext documentation, instead of the current version.
- Refrain from using
- Always include the
.mdextension in the path.
- Select the corresponding directory.
- Add the document id to the corresponding sidebars file. Example:
" components/components-overview",
- Identify the page, pages, or directory and relocate it in the file structure.
- Update the corresponding sidebars file(s) to fit the new location.
- Add necessary redirect/rewrite rules to the top of
.htaccess.
See Redirect rules for information on testing .htaccess rules.
- Identify the page, pages, or directory and delete it in the file structure.
- Update the corresponding sidebars file(s).
- Add necessary redirect/rewrite rules to the top of
.htaccessto redirect users to appropriate relevant content on another page.
See Redirect rules for information on testing .htaccess rules.
The build-docs workflow of each PR runs a step to verify that all links present in the production sitemap are still valid. If your build fails on a link validation step, it likely means you moved a doc and did not add a redirect rule that matches the original path. See the Guide to Writing Redirect Rules for information on writing and testing redirect rules.
When adding BPMN files, place these files in the static/bpmn folder and reference them in your documentation appropriately. If a dedicated folder does not yet exist in the static/bpmn folder for the section of documentation you want to add BPMN files to, create one.
For example, a BPMN diagram in the APIs & tools section is placed in static/bpmn/apis-tools and referenced in the documentation as /bpmn/apis-tools/gettingstarted_quickstart_advanced.bpmn.
In an effort to automate screenshots across Camunda 8 documentation, the following teams execute uniform steps when incorporating images and diagrams:
:::note 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 for details on updating screenshots and scripting new screenshots.
Zeebe
Currently, Zeebe diagrams are stored as BPMN in a repository, and as diagrams within Google Drive. This Google Drive is organized according to the structure of documentation in camunda-docs.
:::note When saving diagrams, do not take manual screenshots. Rather, incorporate diagrams directly by clicking Download > PNG image (.png). :::
Keep the following guidelines in mind when creating Zeebe diagrams:
- The standardized font is Arial. Font size may vary based on diagram size.
- The standardized colors for diagrams are
#0d8dbaand orange with the default background color of white. - Rectangular diagrams should be around 500x1200px, and square diagrams should be around 500x500px.
- There should be no more than nine elements per diagram. Otherwise, complex processes may be broken into more than one diagram.
Operate
Find automation code here. These test files must be adjusted to change screenshots.
A new screenshot run can be triggered manually using GitHub actions. The screenshots can then be downloaded from the workflow.
Tasklist Tasklist screenshot automation is currently in the backlog.
Optimize Most of the screenshots in the user guide can be updated automatically:
- Check out the camunda-optimize repository.
- In the
/clientdirectory of thecamunda-optimizerepository, start the frontend development setup by runningyarn run start-backendandyarn start. - Wait for the data to be generated and imported and then run
yarn run screenshots.
On a technical level, the Optimize team takes screenshots within their end-to-end test cases.
After the proposed change is finished, open a GitHub PR and assign reviewers based on your PR template. Most PRs require a technical writing review and a review from the relevant engineering team.
If unsure about who to pick, choose one of the corresponding team representatives, and they will take care of delegating the issue:
- Console: @ultraschuppi
- Desktop Modeler: @camunda/modeling-dev
- Web Modeler: @marcosbarbero @wollefitz
- Zeebe: @npepinpe
- Operate: @ThorbenLindhauer
- Tasklist: @camunda/human-task-orchestration
- Optimize: @RomanJRW
- Connectors: @camunda/connectors
- Self-Managed/Distribution: @camunda/distribution
- InfEx: @camunda/infrastructure-experience
- Identity: @kevinCamunda
- DevEx: @akeller
- Product Management:
- Core Orchestration and Core Platform topics: @felix-mueller
- Task Automation: @crobbins215
- Business Application Integration: @toco-cam
- Embedded Intelligence, Onboarding and Migration: @bastiankoerber
- Fallback: @bastiankoerber
- Documentation: @camunda/tech-writers
- Documentation infrastructure: @pepopowitz
- Fallback: @akeller
As a reviewer, feel free to merge any PR you feel comfortable with after your review. If you have questions or concerns or feel that you are not the right person to review the PR, please make this transparent to the PR author so they can clarify.