From 909c885659761f46efec1bca253637b096ed3929 Mon Sep 17 00:00:00 2001
From: John Nduli
Date: Tue, 16 Jul 2024 19:13:01 +0300
Subject: docs: add initial docs and prefefences for guides

---
 topics/documentation/guides_vs_references.gmi | 11 +++++++++++
 1 file changed, 11 insertions(+)
 create mode 100644 topics/documentation/guides_vs_references.gmi

(limited to 'topics/documentation')

diff --git a/topics/documentation/guides_vs_references.gmi b/topics/documentation/guides_vs_references.gmi
new file mode 100644
index 0000000..b507623
--- /dev/null
+++ b/topics/documentation/guides_vs_references.gmi
@@ -0,0 +1,11 @@
+# Guides Vs References
+
+Before coming up with docs, figure out their use. It can either be as a guide (provides solutions to problems encountered) or a reference (similar to man pages, where we provide detailed explanations).
+
+For guides:
+
+* Be as brief as possible, providing reference links for users that want to explore i.e. don't aim from completeness, but rather practicality.
+* Prefer providing code or command snippets where possible.
+* Preferable have another team member review the docs. This helps eliminate blindspots due to our current knowledge.
+* Organize the document in such a way that it starts with the most actionable steps.
+* Avoid stream of consciousness writing.
-- 
cgit v1.2.3