Skip to main content

Best Practice Template

This document provides the structure for contributing best practices to the repository. Follow this template to ensure clarity and consistency.

Template​

# Title

Summary of the best practice.

## Description

Further information about the best practice.

## Rationale

Why this best practice is important and why it should be applied.

## Examples

Provide inline examples where possible. If not applicable, include links to example repositories or other references.

## References & Further Reading

Include links to guides, blogs, or documentation that enhance understanding and provide additional context.

* Link Name (URL)
* Example link (https://crukorg.github.io/engineering-guidebook/docs/new-starter)

Writing Guidelines​

When writing a best practice, prioritise clarity and conciseness. Avoid long, unclear paragraphs. Instead, make the reasoning behind the recommendation obvious and easy to follow.

For examples, ensure they are clear and reproducible, removing ambiguity wherever possible.

Categorisation​

Create a new category if needed. For instance:

  • Frontend: For frontend-specific best practices.
  • Backend: For backend-specific best practices.
  • Infrastructure: For infrastructure-specific best practices.
  • Common: For general best practices that apply across categories.

To change the sidebar position of your documentation, add the following to the top of the file. By default, order is determined by filename:

---
sidebar_position: 1
---

Markdown Syntax​

Use standard Markdown syntax for your content. For additional Markdown features, see the Docusaurus Markdown documentation.

Docusaurus Admonitions​

Use Docusaurus admonitions to highlight important content. For example:

:::info

Write mandatory content here.

:::
info

Write mandatory content here.

For more information, refer to the Docusaurus admonition documentation.

Explore further Docusaurus features here.