Skip to content

Latest commit

 

History

History
187 lines (129 loc) · 12.4 KB

documentation-guidelines.md

File metadata and controls

187 lines (129 loc) · 12.4 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 Platform 8 --> introduction-to-camunda-platform-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 Platform versions as follows:

Camunda Platform 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 the "Check internal links" step, it likely means you moved a doc. To resolve, you can add a redirect rule to the .htaccess file, mapping the old URL to the new URL.

Testing redirect rules

The .htaccess file contains redirect rules that are applied to the published site, but it has no effect when running docusaurus locally (via npm start).

If you wish to test .htaccess rules, you have a couple options:

  1. Use online tooling to test rules. Tools like https://htaccess.madewithlove.com/ apply a set of redirect rules to a specific URL. Note that there are edge cases where this tool doesn't give the same results as a published environment.

  2. Use docker compose to spin up a locally-running Apache webserver. This repo includes Docker configuration (Dockerfile and docker-compose.yml) to spin up a local environment that better simulates a published environment. Redirect rules can then be tested directly in a browser.

    The local server is based on the contents of your ./build folder. To start this local server:

    1. Build the docs with npm run build.

    2. Start the server with docker compose up.

    3. Browse http://localhost:3001 and test redirects.

      It is probably best to do this in an incognito browser session, as browsers clutch tightly to 301 redirects.

    4. Clean up the server with docker compose down.

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
  • DevRel/DevEx: @akeller
  • Product Management: @felix-mueller
  • Documentation: @christinaausley (fallback: @akeller)
  • Documentation infrastructure: @pepopowitz (fallback: @akeller)
  • Fallback: @menski

In case you don't know who to assign for an engineering review choose @menski and he will delegate.

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.