[DOCS-1442] Self-Managed deployment guide revamp #2113
Conversation
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
- Create and edit snippets for shared object storage content
- Updates to BYOB page to clarify that it applies to all deployments
- Add a new Requirements page for Self-Managed
- Uses existing snippet imports extensively
- Clear cross-references to reference architecture
- Strong BYOB integration
- Sections:
- Software version requirements
- Hardware requirements
- Kubernetes (with OpenShift mention)
- MySQL database (with config parameters and creation instructions)
- Redis
- Object storage (with BYOB provisioning link and configuration transition)
- Networking (with DNS and load balancer info)
- SSL/TLS
- License
- Next steps (links to cloud, on-prem, airgapped guides)
- Create new directories for details specific to Cloud or on-premise
deployments, will be populated in phases 3 and 4s
- Update navigation
- Move and edit Operator landing page
- Update title
- Use shared BYOB content
- Adjust Before you begin
- Update links for file moves
- Adjust support storage provider list
- Improve cross-references
- Where possible, tabify content for Helm and Terraform to
simplify the giew
- Update navigation
- Create consolidated Terraform guide
- Shared intro, explanation of modules
- Adds a cloud provider selector
- Platform-specific content in tabs
- Prerequisites
- General steps
- Recommendations
- Specific details about Redis, message broker
- Links to more resources
- Update navigation
- Create connected and airgapped on-prem guides - Update requirements - Update navigation This resolves some links that were intentionally left broken after the last phase
Add redirects for files we moved, renamed, or consolidated Temporarily, redirect old Japanese / Korean destinations to English destinations
Contributor
📚 Mintlify Preview Links🔄 Renamed/Moved (1 total)📄 Pages (1)
✨ Added (8 total)📄 Pages (8)
📝 Changed (3 total)📄 Pages (2)
⚙️ Other (1)
🗑️ Deleted (5 total)View deleted files📄 Pages (5)
🤖 Generated automatically when Mintlify deployment succeeds |
Contributor
Delete old files we no longer need
mdlinville
force-pushed
the
operator_docs_revamp
branch
from
c56b49d to
d2312a9
Compare
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
Description
This PR completes a comprehensive restructure of the W&B self-managed deployment documentation to address confusion between deployment guides, consolidate shared requirements, improve discoverability, and incorporate enhanced OpenShift/air-gapped deployment guidance.
Key improvements:
The project was accomplished in 6 phases. Each phase is encapsulated into a commit for iterative review. See Changes by Phase.
Benefits
For Users
For Maintenance
For Support
Major Content Improvements
OpenShift Support
Air-Gapped Deployments
User Experience
Related Issues
Closes DOCS-1442
Changes by Phase
Reviewers: This project was completed in 6 phases, each in a separate commit. I suggest loading and scanning through each commit in sequence, before reviewing the HTML output using the Preview comment.
Phase 1: Foundation + Snippets
**Commit:** https://github.com//pull/2113/changes/6567f8668bb8028197611fd92c25279214dc3f8arequirements.mdxpage consolidating prerequisitesPhase 2: Operator Consolidation
**Commit:** https://github.com//pull/2113/changes/19785806b8a73d3ad60c0d3d5e940c17e54373d8operator.mdxtoself-managed/operator.mdxPhase 3: Cloud Terraform Consolidation
**Commit:** https://github.com//pull/2113/changes/90948936bf0ceebc823bd7e9842a9a06bc7a734faws-tf.mdx,gcp-tf.mdx,azure-tf.mdxinto singlecloud-deployments/terraform.mdxPhase 4: On-Premises Guides
**Commit:** https://github.com//pull/2113/changes/ae58ee25e23e7c92c98480c98ca148b131290d34on-premises-deployments/kubernetes.mdx(replaces bare-metal.mdx)on-premises-deployments/kubernetes-airgapped.mdxPhase 5: Redirects
**Commit:** https://github.com//pull/2113/changes/559d904cfda61f22d0442cf2ff491907120853e1Phase 6: Cleanup
**Commit:** https://github.com//pull/2113/changes/d2312a94f3cf2cb40b0d001c5ac8cda254aa7a2bNew Documentation Structure
Files Removed
- platform/hosting/operator.mdx (moved) - platform/hosting/self-managed/bare-metal.mdx (replaced) - platform/hosting/self-managed/operator-airgapped.mdx (replaced) - platform/hosting/self-managed/aws-tf.mdx (consolidated) - platform/hosting/self-managed/gcp-tf.mdx (consolidated) - platform/hosting/self-managed/azure-tf.mdx (consolidated)Redirects Added
All old URLs redirect to new locations:
English:
/platform/hosting/operator→/platform/hosting/self-managed/operator/platform/hosting/self-managed/bare-metal→/platform/hosting/self-managed/on-premises-deployments/kubernetes/platform/hosting/self-managed/operator-airgapped→/platform/hosting/self-managed/on-premises-deployments/kubernetes-airgapped/platform/hosting/self-managed/aws-tf→/platform/hosting/self-managed/cloud-deployments/terraform/platform/hosting/self-managed/gcp-tf→/platform/hosting/self-managed/cloud-deployments/terraform/platform/hosting/self-managed/azure-tf→/platform/hosting/self-managed/cloud-deployments/terraformLocalized (ja/ and ko/):
Testing Checklist
mint dev,mint validatecat docs.json | python3 -m json.toolFollowup tasks for localization team
Japanese and Korean localized files still exist but redirect to English versions. The localization team should:
Translate new/updated content (5 files):
platform/hosting/self-managed/requirements.mdx(NEW)platform/hosting/self-managed/operator.mdx(enhanced)platform/hosting/self-managed/cloud-deployments/terraform.mdx(NEW)platform/hosting/self-managed/on-premises-deployments/kubernetes.mdx(NEW)platform/hosting/self-managed/on-premises-deployments/kubernetes-airgapped.mdx(NEW)Delete old localized files (6 per language):
ja/platform/hosting/operator.mdxandko/platform/hosting/operator.mdx{ja,ko}/platform/hosting/self-managed/bare-metal.mdx{ja,ko}/platform/hosting/self-managed/operator-airgapped.mdx{ja,ko}/platform/hosting/self-managed/{aws,gcp,azure}-tf.mdxUpdate navigation in
docs.jsonfor ja/ and ko/ sectionsTimeline: No urgency - redirects serve English content until translations ready.
Statistics