diff --git a/docs/contribute/doc-style-guide.md b/docs/contribute/doc-style-guide.md index 3aa56b336f..1e28ed4676 100644 --- a/docs/contribute/doc-style-guide.md +++ b/docs/contribute/doc-style-guide.md @@ -228,6 +228,14 @@ helps downstream localization. - Use (`-`) for unordered lists. - Leave a blank line after each list. - Indent nested lists with two spaces. +- Use a numbered list for a sequence of steps rather than prose with + "First", "Then", and "Finally". Numbered lists are easier to scan, make + the order explicit, and give readers a clear way to reference a specific + step. + +| Do | Don't | +| :----------------------------------------------------------------- | :------------------------------------------------------------------------------ | +| 1) Install the package. 2) Run the migration. 3) Start the server. | First, install the package. Then, run the migration. Finally, start the server. | ### Tables