[docs] Restructure user documentation

[BenjaminPelletier]

This PR formalizes desired characteristics for user documentation in docs/documentation_design.md and then performs a large-scale reorganization of user documentation to better match these characteristics.

I recognize this is a large monolithic change but think it would be prohibitive to partition it into smaller consistent changes. These changes had been soft-introduced in the user-documentation branch on this repo to prepare for this PR and I believe had general alignment, but other priorities delayed creation of a PR until now. This made merging in documentation changes since the original commit more challenging (I was assisted by AI for that merge commit). I think if this PR is delayed longer, that will make additional merges necessary and more prone to mistakes which is why I am proposing it now rather than after cleaning up some things that are currently left unfinished. However, I do think/expect the user documentation should remain fully usable after this PR (at least as usable as before this PR) and if that is not the case, I would like to achieve that outcome before merging. I recommend reviewers start with docs/documentation_design.md.

Suggestions for alternatives to this PR are welcome, though this is the solution that seemed least-bad when I brainstormed approaches.

[the-glu]

The new documentation is nice. I only checked it by browsing locally, but here are a few remarks/questions:

• Pooling and "unpooling" seem unbalanced:
  • The title of the page is "Leaving a Pool" under Operate, but it also links to how to join a pool. I would balance both sides.
  • Nit: Joining is structured as Pooling / [Overview, With CRDB, With Yugabyte], whereas leaving is just two pages. I would align the structure of leaving with joining.
  • Nit in decommission: "After terraform" vs. "Minikube" - should both use "After" or drop it entirely? (Dropping "After" makes more sense).
• deployment_layers.png can be removed (generated files are not cleaned up by the script).
• create_pool_2 / create_pool_n are no longer referenced. Can they be removed?

[the-glu]

Change seems good, but unrelated to the doc no?

[BenjaminPelletier]

Yes, but needed to pass make lint

[the-glu]

Hum, it's working there and in CI, is there something different somewhere? I would expect make lint to be independent of where it is run.

[BenjaminPelletier]

Probably because the shellcheck image isn't pinned for make shell-lint.

Before re-pulling:

echo "===== Checking DSS shell lint =====" && find . -name '*.sh' | grep -v '^./interfaces/astm-utm' | git check-ignore --stdin --no-index -n -v --non-matching | grep '^::' | cut -f2 | xargs docker run --rm -v /usr/local/google/home/pelletierb/IdeaProjects/OpenSource/dss:/dss -w /dss koalaman/shellcheck -x
===== Checking DSS shell lint =====

In ./release/scripts/configure-clusters.sh line 64:
            ( cd "$aws_ws" && ./dss-certs.sh init || true; ) >"$aws_log" 2>&1
                           ^-- SC2015 (info): Note that A && B || C is not if-then-else. C may run when A is true.


In ./release/scripts/configure-clusters.sh line 66:
            ( cd "$goo_ws" && ./dss-certs.sh init || true; ) >"$goo_log" 2>&1
                           ^-- SC2015 (info): Note that A && B || C is not if-then-else. C may run when A is true.

For more information:
  https://www.shellcheck.net/wiki/SC2015 -- Note that A && B || C is not if-t...
make: *** [Makefile:95: shell-lint] Error 123

$ docker image ls | grep shellcheck
koalaman/shellcheck:latest                                                                               9becfd93c531       15.3MB             0B        
koalaman/shellcheck:v0.11.0                                                                              1b75f92cc711       16.2MB             0B

After re-pulling, lint passes without changes and:

$ docker image ls | grep shellcheck
koalaman/shellcheck:latest                                                                               d8ca54211448       17.4MB             0B        
koalaman/shellcheck:v0.11.0                                                                              1b75f92cc711       16.2MB             0B

[the-glu]

This is rendered in a code block instead of a list

[BenjaminPelletier]

• The title of the page is "Leaving a Pool" under Operate, but it also links to how to join a pool. I would balance both sides.

Changed nav title to "Pooling".

• Nit: Joining is structured as Pooling / [Overview, With CRDB, With Yugabyte], whereas leaving is just two pages. I would align the structure of leaving with joining.

There isn't enough overlap to justify a common page for leaving a pool but there is for joining, so leaving has two pages whereas joining includes a common page.

• Nit in decommission: "After terraform" vs. "Minikube" - should both use "After" or drop it entirely? (Dropping "After" makes more sense).

Changed to just "terraform".

• deployment_layers.png can be removed (generated files are not cleaned up by the script).

Removed.

• create_pool_2 / create_pool_n are no longer referenced. Can they be removed?

Removed.