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') 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