Why does Sway help recommend putting the user config in the second priority location? When Sway starts, according to its man page, it looks for a configuration in the following places: 1. ~/.sway/config 2. $XDG_CONFIG_HOME/sway/config (suggested location) 3. ~/.i3/config 4. $XDG_CONFIG_HOME/i3/config 5. /etc/sway/config 6. /etc/i3/config where $XDG_CONFIG_HOME defaults to ~/.config. The man page then recommends creating a user configuration at ~/.config/sway/config. Why would the suggested location be the number 2 in the priority list rather than /.sway/config?

Support for `$XDG_CONFIG_HOME` (part of the XDG Base Directory Specification) was added to sway in this pull request from 16 August 2015 without giving a reason for the particular order in which the directories are searched. i3 (the X11 window manager that's the inspiration for sway) did read `~/.i3/config` first until this pull request from 2018. It's possible the sway code was based on the i3 one, but unless the author of the code in sway adds some information here, that's just speculation.

The section in the man page was added in this commit from 18 August 2015 which - once again - doesn't state a reason for the particular order. This still leaves only speculation as to why.

I think your only chance of getting a useful answer is opening an issue against sway or ask in the #sway IRC channel on Freenode.