From 58f62567da0029644f4c184c2ea42241e111b5ef Mon Sep 17 00:00:00 2001 From: Dave Wilding Date: Thu, 16 Jan 2025 08:05:45 +0800 Subject: [PATCH 1/2] Added style tips for writing docs --- HACKING.md | 12 ++++++++++++ 1 file changed, 12 insertions(+) diff --git a/HACKING.md b/HACKING.md index 8424b2eb1..53ce50f9b 100644 --- a/HACKING.md +++ b/HACKING.md @@ -262,6 +262,18 @@ before generating docs to recompile the `requirements.txt` file used for docs: tox -e docs-deps ``` +## How to write a great doc + +- Use short sentences, ideally with one or two clauses. +- Use headings to split the doc into sections. Make sure that the purpose of each section is clear from its heading. +- Avoid a long introduction. Assume that the reader is only going to scan the first paragraph and the headings. +- Avoid background context unless it's essential for the reader to understand. + +Recommended tone: +- Use a casual tone, but avoid idioms. Common contractions such as "it's" and "doesn't" are great. +- Use "we" to include the reader in what you're explaining. +- Avoid passive descriptions. If you expect the reader to do something, give a direct instruction. + ## How to Pull in Style Changes The documentation uses Canonical styling which is customised on top of the [Furo Sphinx theme](https://github.com/pradyunsg/furo). The easiest way to pull in Canonical style changes is by using the Canonical documentation starter pack, see [docs](https://canonical-starter-pack.readthedocs-hosted.com/) and [repository](https://github.com/canonical/sphinx-docs-starter-pack). From df378c94e963112610cfdb1bf0a62ce8db6f8367 Mon Sep 17 00:00:00 2001 From: Dave Wilding Date: Thu, 16 Jan 2025 09:25:39 +0800 Subject: [PATCH 2/2] Suggestion from James --- HACKING.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/HACKING.md b/HACKING.md index 53ce50f9b..4cac930a7 100644 --- a/HACKING.md +++ b/HACKING.md @@ -262,7 +262,7 @@ before generating docs to recompile the `requirements.txt` file used for docs: tox -e docs-deps ``` -## How to write a great doc +## How to write great documentation - Use short sentences, ideally with one or two clauses. - Use headings to split the doc into sections. Make sure that the purpose of each section is clear from its heading.