[jackhill/qmk/firmware.git] / docs / documentation_best_practices.md

# Documentation Best Practices

This page exists to document best practices when writing documentation for QMK. Following these guidelines will help to keep a consistent tone and style, which will in turn help other people more easily understand QMK.

# Page Opening

Your documentation page should generally start with an H1 heading, followed by a 1 paragraph description of what the user will find on this page. Keep in mind that this heading and paragraph will sit next to the Table of Contents, so keep the heading short and avoid long strings with no whitespace.

Example:

```
# My Page Title

This page covers my super cool feature. You can use this feature to make coffee, squeeze fresh oj, and have an egg mcmuffin and hashbrowns delivered from your local macca's by drone.
```

# Headings

Your page should generally have multiple "H1" headings. Only H1 and H2 headings will included in the Table of Contents, so plan them out appropriately. Excess width should be avoided in H1 and H2 headings to prevent the Table of Contents from getting too wide.

# Styled Hint Blocks

You can have styled hint blocks drawn around text to draw attention to it.

### Important

```
!> This is important
```

Renders as:

!> This is important

### General Tips

```
?> This is a helpful tip.
```

Renders as:

?> This is a helpful tip.


# Documenting Features

If you create a new feature for QMK, create a documentation page for it. It doesn't have to be very long, a few sentences describing your feature and a table listing any relevant keycodes is enough. Here is a basic template:

```markdown
# My Cool Feature

This page describes my cool feature. You can use my cool feature to make coffee and order cream and sugar to be delivered via drone.

## My Cool Feature Keycodes

|Long Name|Short Name|Description|
|---------|----------|-----------|
|KC_COFFEE||Make Coffee|
|KC_CREAM||Order Cream|
|KC_SUGAR||Order Sugar|
```

Place your documentation into `docs/feature_<my_cool_feature>.md`, and add that file to the appropriate place in `docs/_sidebar.md`. If you have added any keycodes be sure to add them to `docs/keycodes.md` with a link back to your feature page.
Commit	Line	Data
d8e29b53	1	# Documentation Best Practices
	2
	3	This page exists to document best practices when writing documentation for QMK. Following these guidelines will help to keep a consistent tone and style, which will in turn help other people more easily understand QMK.
	4
	5	# Page Opening
	6
af37bb2f	7	Your documentation page should generally start with an H1 heading, followed by a 1 paragraph description of what the user will find on this page. Keep in mind that this heading and paragraph will sit next to the Table of Contents, so keep the heading short and avoid long strings with no whitespace.
d8e29b53	8
	9	Example:
	10
	11	```
	12	# My Page Title
	13
	14	This page covers my super cool feature. You can use this feature to make coffee, squeeze fresh oj, and have an egg mcmuffin and hashbrowns delivered from your local macca's by drone.
	15	```
	16
	17	# Headings
	18
	19	Your page should generally have multiple "H1" headings. Only H1 and H2 headings will included in the Table of Contents, so plan them out appropriately. Excess width should be avoided in H1 and H2 headings to prevent the Table of Contents from getting too wide.
	20
	21	# Styled Hint Blocks
	22
	23	You can have styled hint blocks drawn around text to draw attention to it.
	24
303f425c	25	### Important
303f425c	26
4c7c7747	27	```
303f425c	28	!> This is important
4c7c7747	29	```
4c7c7747	30
303f425c	31	Renders as:
d8e29b53	32
303f425c	33	!> This is important
4c7c7747	34
303f425c	35	### General Tips
4c7c7747	36
4c7c7747	37	```
303f425c	38	?> This is a helpful tip.
4c7c7747	39	```
4c7c7747	40
303f425c	41	Renders as:
	42
	43	?> This is a helpful tip.
4c7c7747	44
9d1a08e3	45
	46	# Documenting Features
	47
af37bb2f	48	If you create a new feature for QMK, create a documentation page for it. It doesn't have to be very long, a few sentences describing your feature and a table listing any relevant keycodes is enough. Here is a basic template:
9d1a08e3	49
	50	```markdown
	51	# My Cool Feature
	52
	53	This page describes my cool feature. You can use my cool feature to make coffee and order cream and sugar to be delivered via drone.
	54
	55	## My Cool Feature Keycodes
	56
	57	\|Long Name\|Short Name\|Description\|
	58	\|---------\|----------\|-----------\|
	59	\|KC_COFFEE\|\|Make Coffee\|
	60	\|KC_CREAM\|\|Order Cream\|
	61	\|KC_SUGAR\|\|Order Sugar\|
	62	```
	63
303f425c	64	Place your documentation into `docs/feature_<my_cool_feature>.md`, and add that file to the appropriate place in `docs/_sidebar.md`. If you have added any keycodes be sure to add them to `docs/keycodes.md` with a link back to your feature page.