From 3df2ffa6f614d2775a6775987d214cf655dbd926 Mon Sep 17 00:00:00 2001
From: Andrew David Wong <adw@andrewdavidwong.com>
Date: Mon, 23 Nov 2020 07:08:35 -0800
Subject: [PATCH] Add guideline on syntactically distinguishing variables in
 commands

---
 developer/general/doc-guidelines.md | 13 +++++++++++++
 1 file changed, 13 insertions(+)

diff --git a/developer/general/doc-guidelines.md b/developer/general/doc-guidelines.md
index 04c327a4..e03640b2 100644
--- a/developer/general/doc-guidelines.md
+++ b/developer/general/doc-guidelines.md
@@ -241,6 +241,19 @@ Style Guidelines
 
  * Familiarize yourself with the terms defined in the [glossary]. Use these
    terms consistently and accurately throughout your writing.
+ * Syntactically distinguish variables in commands.
+   For example, this is ambiguous:
+
+       $ qvm-run --dispvm=dvm-template --service qubes.StartApp+xterm
+
+   It should instead be:
+
+       $ qvm-run --dispvm=<DVM_TEMPLATE> --service qubes.StartApp+xterm
+
+   Note that we syntactically distinguish variables in three ways:
+   1. Surrounding them in angled brackets (`< >`)
+   2. Using underscores (`_`) between words
+   3. Using all capital letters
 
 
 Markdown Conventions