From 881a7423a76e6cdd5ec6eca6738612f9197fc337 Mon Sep 17 00:00:00 2001
From: John Nduli
Date: Tue, 16 Jul 2024 19:13:17 +0300
Subject: docs: add example for guide preference

---
 topics/documentation/guides_vs_references.gmi | 12 ++++++++++++
 1 file changed, 12 insertions(+)

(limited to 'topics')

diff --git a/topics/documentation/guides_vs_references.gmi b/topics/documentation/guides_vs_references.gmi
index b507623..e5d2acb 100644
--- a/topics/documentation/guides_vs_references.gmi
+++ b/topics/documentation/guides_vs_references.gmi
@@ -9,3 +9,15 @@ For guides:
 * 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.
+
+## Example
+### Wrong
+
+When setting up guix OS, I couldn't get `tmux` to start, getting `tmux: invalid LC_ALL, LC_CTYPE or LANG`. Running `locale -a` failed too. It took me a while to figure out the solution for this problem, and I attempted to reinstall `glibc-locales` which didn't help. After a lot of research, I found that the root cause was that my applications were built on a different version of `glibc`. I ran `guix update` and the problem disappeared.
+
+### Correct
+
+`tmux` failing with `tmux: invalid LC_ALL, LC_CTYPE or LANG` could be caused by having packages build on a different version of `glibc`. Attempt:
+
+> locale -a # should also fail
+> guix update # rebuilds your packages with your current glibc
-- 
cgit v1.2.3