docs/filesystem: Weaken stateoverlay wording and direct to alternatives

We wrote the code and it is useful. We are probably just going
to need to support it into the forseeable future. However, my
core problem with it is what I wrote in the docs here: it has
no equivalent in the docker/podman ecosystem, which I think
cuts against a core principle that we're trying to make
the booted host align with containers.

Of course, stateoverlay isn't a lot of code, and in theory
it's a bit independent of ostree, so perhaps we could try to
split it out at some point and then it could be used by e.g.
`podman run --mount=type=stateoverlay` or so.

Before anyone starts just blindly enabling stateoverlays
I'd like them to have considered alternatives such as the
symlink approach.

Signed-off-by: Colin Walters <[email protected]>

Author: cgwalters

docs/src/filesystem.md

@@ -225,12 +225,25 @@ More on prepare-root: <https://ostreedev.github.io/ostree/man/ostree-prepare-roo
 
 This feature enables a writable overlay on top of `/opt` (or really, any
 toplevel or subdirectory baked into the image that is normally read-only).
-Changes persist across reboots but during updates, new files from the container
-image override any locally modified version. All other files persist.
 
-To enable this feature, simply instantiate the `[email protected]`
+The semantics here are somewhat nuanced:
+
+- Changes persist across reboots by default
+- During updates, new files from the container image override any locally modified version
+
+A disadvantage of this approach is that there is no equivalent to this feature in the
+Docker/podman ecosystem, and while its semantics can often trivially enable many applications that
+install into `/opt`, it can still be prone to "state drift".
+
+To enable this feature, instantiate the `[email protected]`
 unit template on the target path. For example, for `/opt`:
 
 ```
 RUN systemctl enable [email protected]
 ```
+
+### Alternatives to state overlays
+
+See the section on `/opt` in [Image building and configuration guidance](building/guidance.md).
+Essentially, add a redirect such as a symbolic link from `/opt/someapp/logs` or other
+directories that should be writable+persistent to `/var/someapp/logs` instead.