From bfdce5ef30f78ca4c0c03308eff0bf123fc60a7a Mon Sep 17 00:00:00 2001
From: Moritz Poldrack <33086936+mpldr@users.noreply.github.com>
Date: Wed, 9 Nov 2022 20:16:22 +0100
Subject: [PATCH] update documentation to reflect best-practices (#857)

* update tailscale.md to reflect best-practices

The provided -Syy is supposed to be used to redownload all package databases,
while the command chain itself is a partial upgrade which is not recommended
either for rolling release distributions.

Replace the full database redownload with a database update and run a system
upgrade while installing tailscaled.

* remove unnecessary sync command from video.md

* remove unnecessary sync command from bluetooth_hid.md

* remove unnecessary sync command from arduino_hid.md

* update faq.md to reflect best practices

* update letsencrypt.md to keep system up-to-date when installing packages
---
 docs/arduino_hid.md   | 3 +--
 docs/bluetooth_hid.md | 3 +--
 docs/faq.md           | 4 ++--
 docs/letsencrypt.md   | 4 ++--
 docs/tailscale.md     | 3 +--
 docs/video.md         | 3 +--
 6 files changed, 8 insertions(+), 12 deletions(-)

diff --git a/docs/arduino_hid.md b/docs/arduino_hid.md
index 1f0c719d..f63db7eb 100644
--- a/docs/arduino_hid.md
+++ b/docs/arduino_hid.md
@@ -179,8 +179,7 @@ Programming assumes the Arduino is powered via USB, either from the connected ho
 As of the latest package release, the kdmd service supports SPI. It should be sufficient to ensure the packages are up-to-date with the latest release, the programmer is installed, and the SPI device overlay is loaded at boot.
 
 * Switch the filesystem to read-write mode with `rw`
-* Update the system with `pacman -Syu` for the latest packages
-* Install the avrdude programmer with `pacman -S avrdude-svn`
+* Update the system and nstall the avrdude programmer `pacman -Syu avrdude-svn`
 * Add `dtoverlay=spi0-1cs` to `/boot/config.txt`
 * Reboot with `reboot` or `systemctl reboot`
 
diff --git a/docs/bluetooth_hid.md b/docs/bluetooth_hid.md
index cbefe8d9..507b3cd3 100644
--- a/docs/bluetooth_hid.md
+++ b/docs/bluetooth_hid.md
@@ -16,8 +16,7 @@ This is not the main case of using PiKVM since you still need it to pair with a
 
     ```
     # rw
-    # pacman -Syu
-    # pacman -S bluez bluez-utils raspberrypi-bluetooth
+    # pacman -Syu bluez bluez-utils raspberrypi-bluetooth
     ```
 
 2. Edit `/boot/config.txt` and comment these lines:
diff --git a/docs/faq.md b/docs/faq.md
index eba26152..ff24c25d 100644
--- a/docs/faq.md
+++ b/docs/faq.md
@@ -243,9 +243,9 @@ As a first step, we recommend carefully reading our documentation on [GitHub](ht
     PiKVM OS is based on Arch Linux ARM and uses the [pacman](https://wiki.archlinux.org/title/Pacman) package manager.
 
     * Switch filesystem to RW-mode: `rw`.
-    * Update the package cache: `pacman -Syy`.
     * Find some packages (`emacs` for example): `pacman -Ss emacs`.
-    * Install it: `pacman -S emacs`.
+    * Install it, while keeping the system updated: `pacman -Syu emacs`.
+    * To only update packages without installing new ones, use `pacman -Syu`
     * Remove it: `pacman -R emacs`.
     * Switch filesystem to RO-mode: `ro`.
 
diff --git a/docs/letsencrypt.md b/docs/letsencrypt.md
index 136e9bdc..efcb425f 100644
--- a/docs/letsencrypt.md
+++ b/docs/letsencrypt.md
@@ -52,7 +52,7 @@ This example shows that PiKVM may not be accessible from the internet, but you c
 1. Switch filesystem to RW and install the Cloudflare DNS plugin:
    ```
    # rw
-   # pacman -S certbot-dns-cloudflare
+   # pacman -Syu certbot-dns-cloudflare
    ```
 
 2. Prepare the environment for the DNS plugin (place the auth data):
@@ -84,7 +84,7 @@ This example shows that PiKVM may not be accessible from the internet, but you c
 1. Switch filesystem to RW and install the Route53 DNS plugin:
    ```
    # rw
-   # pacman -S certbot-dns-route53
+   # pacman -Syu certbot-dns-route53
    ```
 
 2. Configure Your AWS User
diff --git a/docs/tailscale.md b/docs/tailscale.md
index aa70dd78..d424cc77 100644
--- a/docs/tailscale.md
+++ b/docs/tailscale.md
@@ -11,8 +11,7 @@
 
     ```
     # rw
-    # pacman -Syy
-    # pacman -S tailscale-pikvm
+    # pacman -Syu tailscale-pikvm
     # systemctl enable --now tailscaled
     # tailscale up
     ```
diff --git a/docs/video.md b/docs/video.md
index 78e24cb2..7ba3006e 100644
--- a/docs/video.md
+++ b/docs/video.md
@@ -9,8 +9,7 @@
 
     ```
     # rw
-    # pacman -Syu
-    # pacman -S ffmpeg
+    # pacman -Syu ffmpeg
     ```
 
 2. For USB dongle only: Add line `gpu_mem=256` to `/boot/config.txt`.