[PATCH 1/2] Clarify disco only is required for dynamic peers

General
1

Back in early April this year, shortly after doing my initial syncthing setup, I joined the irc room and posted two very minor documentation patch suggestions. While I quickly realized noone of all the channel members were the right audience, it was only recently learned that the channel is unofficial and has been removed from documentation.

Given the patches still seem to rebase cleanly on v1.28.1, they might perhaps be relevant enough to try posting here on the forum.

The first patch merely suggests injecting a single word. In order to hopefully clarify when a disco server is required, and when it is not.

From 52851f67e1b58bf38012645d544717083b5750c8 Mon Sep 17 00:00:00 2001
From: cos <cos>
Date: Fri, 5 Apr 2024 10:17:29 +0200
Subject: [PATCH 1/2] Clarify disco only is required for dynamic peers

This single extra word should hopefully not be too confusing for those
who do not look for it, yet it could save others the hassle of spending
half-an-hour installing and setting up an stdiscosrv just to realize the
problem was elsewhere (like I did).
---
 users/stdiscosrv.rst | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/users/stdiscosrv.rst b/users/stdiscosrv.rst
index fd43f93..1c73f39 100644
--- a/users/stdiscosrv.rst
+++ b/users/stdiscosrv.rst
@@ -15,8 +15,8 @@ Synopsis
 Description
 -----------
 
-Syncthing relies on a discovery server to find peers on the internet. Anyone
-can run a discovery server and point Syncthing installations to it. The
+Syncthing relies on a discovery server to find dynamic peers on the internet.
+Anyone can run a discovery server and point Syncthing installations to it. The
 Syncthing project also maintains a global cluster for public use.
 
 Options
-- 
2.46.1

Please feel free to consider or comment as you see fit. Hopefully this General forum category is appropriate enough. It felt like a stretch to post this under Development.

2

Could you open a PR? Seems more appropriate and simpler to review and discuss any changes there. Or even better if it’s a tiny and/or obviously good change, no discussion at all is needed, it can be merged and be usable by everyone asap.

This particular change I am not overly keen on. Just injecting a general purpose adjective imo doesn’t add clarity. I can make the link to the config option when I think about the word in particular, I doubt I would have made the connection if I read it in passing instead of in a diff, and I doubt anyone not super familiar with syncthing will make it. And other than that, I don’t think think “dynamic peer” has any intrinsic meaning.

1 Like
3

A pull request, on Microsoft GitHub? To make things simpler‽ Nah! I would rather not. Would Radicle be a preferred option to patches on this forum?

The patch came out of my experience as someone completely new to ST, who got the impression that discosrv was an absolutely required component. I believe the suggested extra word would had been enough for me to instead had wondered what it meant. I’d argue that it doesn’t need to have intrinsic meaning. It just needs be consistent with how it is used in other parts of the documentation. The goal is to help the user grasp how the pieces fit together, without having to revert to learning by attempting the wrong things.

If anyone can’t think of a better way to describe how totally optional discovery actually is, that would likely help the next new guy.