Skip to content

Latest commit

 

History

History
202 lines (142 loc) · 13.2 KB

documentation-guidelines.md

File metadata and controls

202 lines (142 loc) · 13.2 KB
Raw

Documentation Guidelines

PRs for every change

All changes have to 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 build (including a broken links check).

PRs should be in a draft status while being actively worked. Removing a PR from draft status indicates they are ready for review (by a technical writer).

Labeling PRs

PRs can be labeled “hold” by engineering teams 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 labeled “bug” will be merged and released as immediately as possible.

Not all PRs require an issue

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.

Structure

  • 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 internal document id to reference in the appropriate sidebars file.
  • Sub categories have to be placed in their own sub directories. Example: Guides/Update Guide can be found in docs/guides/update-guide.

Instances: Docs vs Optimize

Due to a difference in version numbers, the documentation is split into multiple Docusaurus "instances". Documentation specific to Optimize lives in the optimize instance, and all other documentation lives in the main docs instance.

Versions

Each instance of the documentation contains documentation for multiple versions:

Instance Version(s) Source path
docs Next /docs/
docs 8.1, 8.0, 1.3, ... /versioned_docs/version-*/
optimize Next /optimize/
optimize 3.9.0, 3.8.0, 3.7.0, ... /optimize_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.

Version alignment

Specific Optimize versions are aligned with Camunda versions as follows:

Camunda version Optimize version
8.1 3.9.0
8.0 3.8.0
1.3 3.7.0

Sidebar navigation

Sidebar navigation of the documentation is managed in the sidebars files. Each instance of the documentation has its own sidebars file:

Instance Version(s) Sidebars path
docs Next /docs/sidebars.js
docs 8.1, 8.0, 1.3, ... /versioned_sidebars/version-*-sidebars.json
optimize Next /optimize/sidebars.js
optimize 3.9.0, 3.8.0, 3.7.0, ... /optimize_versioned_sidebars/version-*-sidebars.json/

Sidebar items

The large object in each sidebars file contains two different types of items:

Note The "next" versions of the docs are JavaScript rather than JSON. As such, cross-instance sidebar items in these files call a helper function instead of emitting the entire cross-instance object for each item.

Synchronization of sidebars

Several sections of the sidebar navigation are shared across the Optimize and main sections of the docs: Components, Self-Managed, and APIs & Clients. For these sections, the structure of the sidebars should always match across instances. When they drift, it appears to the user as differences in the sidebar navigation depending on which page they're viewing.

Any PRs that make a structural change to one of the instance's sidebars file in a shared section should make the same structural change to the other instance's sidebars file. This typically appears as a link to the target .md file in one file, and an object containing the target title and URL in the other file.

Note Changes outside of the shared sections do not need to be synchronized to the corresponding Optimize sidebars file.

Internal links

When linking internally from one document to another, follow these guidelines:

  • if the source and target document are within the same instance (i.e. both are in docs or both are in optimize):
    • 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.
    • Always include the .md extension in the path.
  • if the source and target document are in different instances (i.e. one is in docs and the other is in optimize):
    • If the source is in docs and the target is in optimize, use the $optimize$ token to prefix the URL. See example.
    • If the source is in optimize and the target is in docs, use the $docs$ token to prefix the URL. See example.
    • Use the browser-facing URL to the target document, instead of the path to the target's .md file.
    • Do not include the .md extension on the target path.

Adding a new documentation page

  1. Select the corresponding directory.
  2. Add the document id to the corresponding sidebars file. Example: 
    " components/components-overview",
  3. If the doc is in one of the shared sections, add a parallel change to the other instance's corresponding sidebars file. Example: 
    {
  "type": "link",
  "label": "Overview Components",
  "href": "/docs/components/"
},

Moving an existing page

  1. Identify the page, pages, or directory and relocate it in the file structure.
  2. Update the corresponding sidebars file(s) to fit the new location.
  3. If the doc is in one of the shared sections, update the opposite instance's corresponding sidebars file(s).
  4. Add necessary redirect/rewrite rules to the top of .htaccess.

See Redirect rules for information on testing .htaccess rules.

Remove an existing page

  1. Identify the page, pages, or directory and delete it in the file structure.
  2. Update the corresponding sidebars file(s).
  3. If the doc is in one of the shared sections, update the opposite instance's corresponding sidebars file(s).
  4. Add necessary redirect/rewrite rules to the top of .htaccess to redirect users to appropriate relevant content on another page.

See Redirect rules for information on testing .htaccess rules.

Redirect 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.

Screenshot automation

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. :::

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, we should not take manual screenshots. Rather, authors should incorporate diagrams directly via 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 #0d8dba and 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 & Tasklist Operate and Tasklist screenshot automation is currently in the backlog.

Optimize Most of the screenshots in the user guide can be updated automatically:

  1. Check out the camunda-optimize repository.
  2. In the /client directory of the camunda-optimize repository, start the frontend development setup by running yarn run start-backend and yarn start.
  3. 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.

Review Process

After the proposed change is finished open a GitHub PR and assign at least one reviewer, it is good to pick a reviewer who is expert in the matter of the change. If unsure about who to pick choose one of the corresponding team representatives, and they will take care of delegating the issue:

  • Console: @ultraschuppi
  • Modeler: @camunda/modeling-dev
  • Zeebe: @npepinpe
  • Operate/Tasklist: @ralfpuchert
  • Optimize: @RomanJRW
  • Connectors: @camunda/connectors
  • Self-Managed/Distribution: @camunda/distribution
  • DevEx: @akeller
  • Product Management: @felix-mueller
  • Documentation: @christinaausley
  • Documentation infrastructure: @pepopowitz
  • Fallback: @akeller

As a reviewer feel free to merge any PR which you feel comfortable with after your review. If you have questions, 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 this.