I would say that the exampleSite should be avoided if possible. Some of the @digitalcraftsman themes are so “custom” that it makes sense (we would not be able to build a demo without it) – but it doesn’t help us in the ultimate goal of portability.
If themes are very simple with self-explaining config files there will might be no need to create an exampleSite folder.
However, as @bep already mentioned, some themes are much more complex and offer much options for customizations. In general, I try to add concise comments in the config file. In the README I have a more detailed setup guide for a theme.
If themes are even more complex I add the documentation to the exampleSite directory and link to the demo site - for the Material docs theme it serves a double pupose.
How you document your theme is mostly depended on how customizable your theme can be.