Add documentation improvement plan doc#240
Add documentation improvement plan doc#240hossain-rayhan wants to merge 1 commit intodocumentdb:mainfrom
Conversation
Signed-off-by: Rayhan Hossain <rhossain@microsoft.com>
There was a problem hiding this comment.
Pull request overview
This PR adds a comprehensive documentation improvement plan that outlines a structured approach to enhance the DocumentDB Kubernetes Operator documentation from its current preview state to production-ready documentation.
Changes:
- Adds a detailed 9-phase documentation improvement plan with 37 tasks covering all aspects of operator documentation
- Proposes a new documentation structure organized into logical categories (getting-started, architecture, configuration, operations, high-availability, disaster-recovery, security, monitoring, troubleshooting, and reference)
- Establishes documentation guidelines that separate executable scripts (in documentdb-playground/) from documentation content
xgerman
left a comment
xgerman
left a comment
There was a problem hiding this comment.
As part of this work:
- We will need a documentation agent
- Where are we putting fleet and kamado?
- How do we do "How to get help?" on the main page or a doc page
- It's light on How to contrinute? File bugs, etc? But that might be ok
| │ ├── installation.md # Detailed installation | ||
| │ ├── deploy-on-aks.md # Azure AKS deployment guide | ||
| │ ├── deploy-on-eks.md # AWS EKS deployment guide | ||
| │ ├── deploy-on-gke.md # GCP GKE deployment guide |
There was a problem hiding this comment.
we need kind and k3s as well since we have that, I think quickstart is kind?
There was a problem hiding this comment.
Yea, we have kind quickstart. But I do feel we should add kind and k3s to streamline.
| │ ├── scaling.md # Scaling procedures | ||
| │ ├── upgrades.md # Operator and cluster upgrades | ||
| │ ├── failover.md # Failover procedures | ||
| │ └── maintenance.md # Node maintenance, rolling updates |
There was a problem hiding this comment.
we can also restore a deleted cluster - make this a chapter as well
There was a problem hiding this comment.
sure. Is it separate from backup and restore?
| │ └── maintenance.md # Node maintenance, rolling updates | ||
| ├── high-availability/ | ||
| │ ├── overview.md # HA concepts and setup | ||
| │ └── multi-instance-clusters.md # Local HA configuration |
There was a problem hiding this comment.
shoudln't we cal it local HA?
There was a problem hiding this comment.
Yea, local-HA sounds cleaner.
| ├── high-availability/ | ||
| │ ├── overview.md # HA concepts and setup | ||
| │ └── multi-instance-clusters.md # Local HA configuration | ||
| ├── disaster-recovery/ |
There was a problem hiding this comment.
just call this multi-region/multi-cloud - people wouldn't expect deployment guides under this chapter.
There was a problem hiding this comment.
disaster-recovery sounds like an industry jargon. Will rename.
| ├── monitoring/ | ||
| │ ├── overview.md # Monitoring setup | ||
| │ └── metrics.md # Prometheus metrics reference | ||
| ├── troubleshooting/ |
There was a problem hiding this comment.
also add a tuning guide here as well
There was a problem hiding this comment.
what would be in that file?
| │ ├── kubectl-plugin.md # Existing plugin docs | ||
| │ └── labels-annotations.md # Labels/annotations reference | ||
| ├── faq.md # Expanded FAQ | ||
| └── release-notes.md # Version history |
There was a problem hiding this comment.
we also have an adopteres file, how to contribute. etc. - where are those going?
There was a problem hiding this comment.
will add one contribute file
| ### Phase 5: Security Documentation | ||
|
|
||
| #### 5.1 Security Overview Page | ||
| **File:** `security/overview.md` |
There was a problem hiding this comment.
also how to submit security issues confidentially
There was a problem hiding this comment.
Do we have a real way other than GitHub at this moment?
| ## Proposed Documentation Structure | ||
|
|
||
| ``` | ||
| docs/operator-public-documentation/ |
There was a problem hiding this comment.
do we need to document our playground here?
|
|
||
| ### Scripts and Examples Pattern | ||
|
|
||
| **Keep scripts in `documentdb-playground/` and reference from docs.** Do not embed full scripts in documentation. |
There was a problem hiding this comment.
The playgrounds contain a lot of README.md files with a lot of context. Should that information move into the docs, leaving those README.md files more as just runbooks? Maybe we can include a guideline here about what should be documented there and what should be here.
4 participants
No description provided.