Skip to main content

Best Practice Template

This document outlines the templated structure for best practices. This should be used when contributing a best practice to the repository.

Template​

# Title

Summary of the best practice.

## Description

Further information around the best practice.

## Rationale

A description on why this best practice is important and why it should be applied.

## Examples

Inline examples are preferred. Where not applicable having links to example repositories or other references can be used.

## References & Further Reading

Include links to guides, blogs and documentation that further enhances the reasoning of this best practice and gives the reader further insight should they wish to learn more.

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

Clarity​

When writing a best practice make the text very clear and easy to understand. Having less text is preferred over unclear paragraphs of information.

Make it obvious why this change is recommended.

For examples make it clear and easily reproducible. Remove and reduce ambiguous points.

Categorizing​

As necessary create a new category if a best practice requires it. For example best practices that are specific to frontend should be within a Frontend category, the same applies for Backend, Infrastructure, e.t.c.

Best practices that are not specific to one category should be within the common category.

The following code can be added to the top of the file should you wish to change the position of the documentation. By default, the order is determined by filename.

---
sidebar_position: 1
---

Markdown​

Standard Markdown syntax is used.

See the following documentation here for all Markdown features: https://docusaurus.io/docs/markdown-features

Docusaurus​

For further Docusaurus specific features see here: https://docusaurus.io/docs/docs-introduction