If you use iCloud drive for document synchronization, you may run into various issues. The big problem is that Apple doesn't really provide control or information on what is happening. It should all work seamless, but it often doesn't.

For Apple, I can recommend to test it not just with a few documents, but with e.g. a million documents in Documents folder and then change 5000 of them on a day.

Let me provide some insights:

• The reported status via the I button in the Finder sidebar is inaccurate. It may show uploading one file, but actually it is uploading 50 files. Also it often sits at over 90% while waiting for some confirmation from Apple servers.
• The app may do a rescan of your folders, which may take a day and cause sync to stall for hours.
• In Activity Monitor you can check the bird application, which is the daemon doing the work.
• The network connection can be stuck sometimes. No data transfer, but files need to be uploaded. Sometimes, but not always, it seems to help to loose internet connection by turning Wifi off and then when you turn it back on, the bird application restarts doing work.
• You can use "killall bird" in Terminal to quickly restart the background app, if it doesn't make progress for hours.
• I wrote myself a little utility app with FSEvents to report on what files changed*. This way I can monitor synchronization and see which folder is going currently. You know, it may show no meaningful progress in Finder, but actually it downloads new files in background.
• You can watch "~/Library/Application Support/CloudDocs/session/i" folder. This is the one for pending uploads. When you change a file and it's not sent immediately, it gets a hard link copy there in the queue. You can check there how many files are pending. We even have some apps modified to look there for how many files are there and pause writing more files until the count is smaller, e.g. < 10.
• Sometimes sync takes forever. Just let the Mac sit there over night without sleeping and it may resolve itself. Seems like some server side process to check in a commit with new uploads takes forever. You can use "caffeinate" command in Terminal to prevent sleep.
• Once a month when Finder reports sync complete, you can check the "~/Library/Application Support/CloudDocs/session/i" folder and delete files that are older than a few days. Don't change files from today or yesterday, but older ones look like they got lost and the app forgot to delete them after uploading.
• If you use firewalls (e.g. Little Snitch), make sure cloudd or bird apps from MacOS are not blocked to reach Apple servers (17.x.x.x IPs or apple.com domain).
• Sometimes I leave a Terminal window open running "brctl monitor -g" to see how progress is reported over time. That is better than just using Finder.

If anyone at Apple likes to improve this, I'd love to provide feedback. But so far Apple's Feedback app looks like a black hole.

* Since it is written in Xojo, we may just include it as example for next release of our plugins.