ptgott
commented
3 weeks ago Revisiting this issue, I think it's okay to close it for now without taking action. While the Trusted Clusters guide is our tenth longest (see below), (a) I don't think we have a visible location for the conceptual information at the bottom of the guide and (b) it's not uncommon for us to add conceptual information to the bottom of how-to guides. I'm not sure how stringently we want to separate sequential instructions from conceptual appendices. If we want to enforce a standard, we should create a linter and enforce it across all docs pages.
Our ten longest guides as of ecd5500166d014e6b8c2fc0527f865f455c9f016:
$ find docs/pages -name "*.mdx" -exec wc -l {} \; | sort -n -k1 | tail -n 10
937 docs/pages/admin-guides/management/admin/trustedclusters.mdx
972 docs/pages/admin-guides/api/automatically-register-agents.mdx
977 docs/pages/admin-guides/api/rbac.mdx
989 docs/pages/reference/machine-id/configuration.mdx
1189 docs/pages/connect-your-client/tsh.mdx
1201 docs/pages/reference/cli/tsh.mdx
1539 docs/pages/reference/backends.mdx
1742 docs/pages/reference/cli/tctl.mdx
1800 docs/pages/includes/helm-reference/zz_generated.teleport-kube-agent.mdx
2208 docs/pages/reference/helm-reference/teleport-cluster.mdx
Applies To
/docs/management/admin/trustedclusters/Details
Let's refactor the trusted cluster guide to separate sequential instructions from conceptual and reference information. The how-to guide should still include a brief "How it works" section, but we should abide by the convention of separating the major genres of documentation. In this case, a user needs to piece through conceptual and reference information to find a tutorial, and needs to scroll past the how-to instructions for reference information.
How will we know this is resolved?
We have separated the trusted cluster guide by purpose (how-to guide, conceptual guide, and reference guide).
Related Issues