DOC-5270, DOC-5272, DOC-5273, DOC-5331, DOC-5264 - Migration doc cleanup continued - Troubleshooting, FAQ, Glossary, and overlapping pages

[aimurphy]

The goal of this PR was to clean up the troubleshooting, FAQ, and glossary topics in the migration docs. Unfortunately, these topics shared redundant content with each other and various other pages so the changes sprawled.

Full description of changes

• Combine troubleshooting-scenarios with troubleshooting-tips for one unified troubleshooting page.
  • Centralize the content about proxy logs onto the troubleshooting page. Previous, the content was split across two pages.
  • Address many repetitive pieces of content that were present in the troubleshooting scenarios and FAQs as well as other pages. The two biggest offenders here were manage proxy instances and feasibility checklists.
  • I ended up rewriting effectively all of manage proxy instances because there was only one section left unedited after I dealt with the repeated content.
  • For feasibility checklists, I revised read-only applications (which repeated a troubleshooting scenario), LWTs and other non-idempotent operations (top-level content only), Server-side non-deterministic functions in the primary key (repeated content from manage-proxy-instances), and Authenticator and authorizer configuration. I changed the heading of DSE Advanced workloads and used a DL instead of H3, but otherwise didn't rewrite the content. Other changes to this page were just reorganizing the sections for better flow/thematic grouping.
• Remove the glossary page - All terms are defined elsewhere, such as the FAQ or in the documentation at the relevant point of performance. Many terms are defined or summarized multiple times throughout the documentation. Terms like CQL and SCB are not explicitly defined but they are supplemented with links to relevant documentation.
  • In a few cases there was some accessory information in the glossary that wasn't explicitly provided elsewhere. I made sure to supplement the text with that information. For example, on components.adoc, I added an explicit definition of secondary cluster and reorganized the information about ansible/playbooks.
• Revise the FAQ page to reduce repetition between FAQ and other pages that typically have more information about the subject of the question, add some new questions, and rework existing questions.
  • The sidecar information was only present in the FAQ. I moved it to deployment-infrastructure.adoc for better visibility/relevance, and replaced the FAQ answer with a link.
• In the nav, Troubleshooting and FAQ are no longer nested under Support (this subsection is now gone too)
• On multiple topics, align use of origin/target vs source/target vs source/destination, and provide parenthetical synonyms in some introductions to remind/hint to the user what those terms mean.
• Added some more info about non-ZDM options like in-place migrations and how to handle incompatible clusters.
• Rewrite the intro to connect-clients-to-proxy.adoc.
• Rewrite the intro to the TLS page.

TL;DR (Just tell me what to review)

• Review the entire unified troubleshooting page
• Review the entire manage proxy instances page
• Review the entire FAQ page
• Review the following sections on feasibility checklists:
  • read-only applications
  • LWTs and other non-idempotent operations (but not the first child under it)
  • Server-side non-deterministic functions in the primary key
  • Authenticator and authorizer configuration
• Review the following sections on components.adoc:
  • zdm utility and zdm automation
  • in-place migrations
• On zdm-proxy-migration-paths.adoc, review the incompatible clusters section
• On deployment-infrastructure.adoc, review the sidecar section
• On connect-clients-to-proxy.adoc, review the intro
• On the tls page, review the intro

[skedwards88]

This is an area I am very unfamiliar with, so I wasn't able to review from a perspective of "is all the info that a user needs here and easily findable". I won't be offended if you need to request a second review from someone who knows this area better.

[plpesvc-ds]

Build successful! ✅
Deploying draft.
Deploy successful! View draft