During troubleshooting with a customer we found that it might help to know that initdb will create a symbolic link from data/pg_wal to the custom directory with the option --waldir.
Thank you for the observation. This indeed seems like something we should cover in a bit more detail. How does the proposed patch (attached) look?
The main initdb change, added to Notes, is:
The pg_wal subdirectory will always exist within the data directory. This is where PostgreSQL sends its write-ahead log (WAL) files. Specifying the --waldir option turns this subdirectory entry into a symbolic link. In general, this is only useful if the remote location is on a different physical device. An existing directory must be empty and should not be a mount point. The directory will be created (including missing parents) if necessary.
