Skip to main content
Version: Next Gen

Best practices

To promote consistency, follow the guidelines below and mentioned throughout to keep the process productive and beneficial for all involved.

Content development

  • Verify your content for technical accuracy before submitting your Pull Request.

  • Consult with the Sr. Technical Writer when adding topics or want to propose changes to the content structure. The Sr. Technical Writer maintains the content's quality, reduces duplication, and provides a consistent user experience. They can also strategize how to deliver complex information—for example, adding an explainer video (<90 secs) can help with complex scenarios or issues.

GitHub

  • Create a working branch when introducing logically related changes. This helps you manage your changes through the workflow. We refer to it here as a working branch because it's a workspace to iterate or refine your changes until they can be integrated into the default branch.

  • Keep your branch up-to-date.

  • Check and remove unused personal branches periodically for easy maintenance. Usually, when your branch is merged, you can safely delete it.

Commit messages

Ensure that your commit message is a proper sentence. Refer to this guide on writing good commit messages.

A properly formed git commit subject line should always be able to complete the following sentence:

If applied, this commit will ....

Pull Requests

  • Try to make the review cycle short.

  • Make sure the markdown follows the style guidelines of this project.

  • Perform a self-review of your markdown, especially spelling errors.

  • Verify that the PR does not generate new warnings before pushing your changes. The best way is to run the clear command.

    npm run clear
    yarn build