chore: Rename platform install pages with platform- prefix #1088
Conversation
bebosudo
requested review from
a team,
justinegeffen and
llewellyn-sl
as code owners
✅ Deploy Preview for seqera-docs ready!
To edit notification comments on pull requests, go to your Netlify project configuration. |
🎭 Voice & Tone ReviewI found 142 voice and tone issues across the enterprise documentation files. These issues appear in both the current docs and versioned docs (which are largely duplicates). 🔴 High Priority: Second Person Issues (43 instances)Using third person ("the user", "users") instead of second person ("you"): platform-enterprise_docs/enterprise/overview.md:
platform-enterprise_docs/enterprise/install-platform.md:
platform-enterprise_docs/enterprise/platform-docker-compose.md:
platform-enterprise_docs/enterprise/configuration/reverse_proxy.md:
platform-enterprise_docs/enterprise/testing.md:
🔴 High Priority: Passive Voice Issues (52 instances)platform-enterprise_docs/enterprise/overview.md:
platform-enterprise_docs/enterprise/install-platform.md:
platform-enterprise_docs/enterprise/platform-docker-compose.md:
platform-enterprise_docs/enterprise/platform-helm.md:
platform-enterprise_docs/enterprise/configuration/overview.mdx:
platform-enterprise_docs/enterprise/configuration/pipeline_optimization.md:
platform-enterprise_docs/enterprise/configuration/reverse_proxy.md:
platform-enterprise_docs/enterprise/upgrade.md:
🟡 Medium Priority: Future Tense Issues (31 instances)platform-enterprise_docs/enterprise/platform-docker-compose.md:
platform-enterprise_docs/enterprise/platform-helm.md:
platform-enterprise_docs/enterprise/platform-kubernetes.md:
platform-enterprise_docs/enterprise/configuration/overview.mdx:
platform-enterprise_docs/enterprise/upgrade.md:
🟡 Medium Priority: Hedging Language (16 instances)platform-enterprise_docs/enterprise/install-platform.md:
platform-enterprise_docs/enterprise/platform-docker-compose.md:
platform-enterprise_docs/enterprise/configuration/pipeline_optimization.md:
platform-enterprise_docs/enterprise/configuration/reverse_proxy.md:
platform-enterprise_docs/enterprise/testing.md:
Summary by Category
Notes
Recommended Actions
|
Editorial Review - PR #1088Executive SummaryThis PR renames platform installation pages with the Total Issues Found: 17
Critical Issues1. Inconsistent Product Name CapitalizationFile:
Impact: Brand consistency and professionalism 2. Ambiguous Pronoun ReferenceFile: Current: Suggested: Impact: User comprehension in deployment guidance Medium Priority Issues3. Passive Voice in InstructionsFile:
Impact: Clarity and directness in user instructions 4. Missing Serial CommaFile:
5. Word Choice: "Contact" vs "Reach Out"File:
6. Redundant PhrasingFile:
Minor Issues7. Unnecessary QualifierFile:
8. Note Callout ConcisenessFile:
9. Capitalization in Frontmatter TitlesFile: Current: Positive Observations
RecommendationsHigh Priority
Medium Priority
Low Priority
Files ReviewedAll 45 files across versions 25.1, 25.2, 25.3, and current docs:
Review Status: Complete |
🔍 Clarity ReviewReviewed 56 files across current and versioned enterprise documentation for clarity issues. Summary
Critical Issues by File1.
|
| Term | Occurrences | Priority |
|---|---|---|
| compute environment | 45+ | High |
| Kubernetes cluster | 40+ | High |
| Helm chart | 30+ | High |
| ingress controller | 25+ | High |
| ConfigMap | 20+ | Medium |
| Redis cache | 15+ | Medium |
| WebSocket | 12+ | Medium |
| SSL/TLS termination | 10+ | Medium |
Missing Prerequisites Pattern
All installation/configuration files lack upfront Prerequisites sections.
Recommendations by Priority
High Priority
- Add Prerequisites sections to all 11 installation/configuration guides
- Define core terms on first use: compute environment, Kubernetes cluster, Helm chart
- Split 47 sentences over 30 words
- Expand acronyms on first use: SMTP, SSL, TLS, DNS
Medium Priority
- Convert long sentences to bulleted lists
- Define technical terms inline: WebSocket, Redis cache, ingress controller
- Simplify 23 nested clauses
- Add brief explanations for Kubernetes concepts
Files Needing Most Attention
- install-platform.md - 12 issues
- platform-helm.md - 11 issues
- configuration/overview.mdx - 10 issues
- reverse_proxy.md - 9 issues
- configuration/pipeline_optimization.md - 8 issues
Version Consistency
The versioned documentation (25.1, 25.2, 25.3) contains identical clarity issues. Fixes should be applied to both current docs and all active version branches.
🎭 Voice & Tone ReviewI've reviewed 60 documentation files (including versioned duplicates) for voice and tone consistency. Here's a summary of the findings: Summary of Issues Found
🔴 High Priority: Person IssuesPattern: "users can" / "administrators can" → "you can" or imperative Examples:
These issues appear most frequently in:
🟡 Medium Priority: Passive VoicePattern: "can be configured" → "configure" or "you can configure" Examples:
🟡 Medium Priority: Tense IssuesPattern: "will [verb]" → "[verb]s" (present tense) Examples:
🟢 Low Priority: Hedging LanguagePattern: "you might want to" → direct instruction or "consider" Examples:
Most Affected FilesFiles with the highest concentration of issues:
Note: The versioned docs (version-25.1, 25.2, 25.3) mirror these same issues. Recommendations
Would you like me to help fix these issues? |
📚 Terminology ReviewI've completed a comprehensive terminology review of the 59 changed documentation files. Here are the findings: 🔴 Critical IssuesProduct Name: "Tower" → "Seqera Platform"Multiple files still reference "Tower" instead of "Seqera Platform":
Product Name: "NextFlow" → "Nextflow"Incorrect capitalization in section headers:
🟡 Medium Priority IssuesFeature Name: "Compute Environment" → "compute environment"Should be lowercase when used in prose (not referring to UI):
Abbreviations Without ExpansionFirst use should include full expansion:
🟢 Positive FindingsThese are correctly used throughout:
📊 Summary Statistics
🔧 Recommended Actions
Review conducted by Claude terminology agent | Learn more about doc standards |
📚 Terminology ReviewI've completed a comprehensive terminology review of all 54 enterprise installation documentation files. Excellent news: These files demonstrate exceptional terminology consistency! ✅ Summary
Detailed FindingsProduct Name Consistency ✅All product names are used correctly throughout:
Formatting Conventions ✅All formatting follows the style guide: Configuration properties use backticks:
Environment variables use code formatting:
File names use backticks:
UI elements use bold:
Feature Names ✅
Abbreviations ✅
Files ReviewedCurrent documentation (14 files):
Versioned documentation (40 files):
ConclusionThese enterprise installation documentation files are exemplary and require no terminology corrections. They serve as a model for:
Review performed by terminology agent - checking product names, feature names, formatting conventions, and abbreviation handling |
📝 Documentation Review Summary
Review powered by Claude Code SME agents To apply fixes: Comment |
🔍 Clarity ReviewI've reviewed 60 enterprise documentation files for clarity issues. Here are the findings organized by severity and type. Critical Issues (High Priority)📏 Long Sentences (Over 30 Words)File:
File:
File:
File:
File:
File:
🔤 Undefined JargonFile:
File:
File:
File:
File:
File:
📋 Missing PrerequisitesFile:
File:
File:
File:
File:
Medium Priority Issues🔄 Nominalization PatternsFile:
File:
🎯 Readability IssuesFile:
File:
Versioned Docs NotesThe versioned documentation in Summary Statistics
Recommended Quick Wins
Files Requiring Most Attention
Estimated reading level: Current documentation ranges from Grade 12-14 (college level). With suggested simplifications, this could be reduced to Grade 10-11 while maintaining technical accuracy. |
📝 Documentation Review Summary
Review powered by Claude Code SME agents To apply fixes: Comment |
Editorial Review: PR #1088Review Profile: Comprehensive SummaryThis PR is primarily a technical refactoring with minimal content changes. The changes consist of:
Overall Assessment✅ No critical editorial issues found The changes are clean, consistent, and follow proper documentation conventions. Detailed Findings1. Link Updates (Primary Changes)All internal documentation links have been correctly updated to reflect the new filenames:
Files with link updates:
Editorial Note: All links follow proper Markdown link syntax and relative path conventions. 2. Content ChangeFile: Change: - If you must host your nf-launcher container image on a private image registry...
+ If you host your nf-launcher container image on a private image registry...Analysis:
3. Whitespace CleanupFile: Changes:
File: Changes:
Assessment: ✅ Approved - Technical improvements with no semantic impact. 4. Code Block FormattingFile: Changes:
Assessment: ✅ Approved - Improves code formatting consistency. Issues by Category
Recommendations✅ Approve and MergeThis PR can be approved without changes. All modifications are:
Additional Notes
Verification ChecklistBefore merging, verify:
Review completed by: Claude Code (Comprehensive Editorial Review) |
🎭 Voice & Tone ReviewSummaryReviewed 59 documentation files for voice, tone, and style consistency. Found several patterns that need attention:
Severity
Common Patterns Across All FilesMost Frequent Issues
Priority RecommendationsPriority 1 (High Impact)
Priority 2 (Medium Impact)
Files Requiring Immediate AttentionBased on severity and frequency of issues:
Note: Versioned documentation files (version-25.1, 25.2, 25.3) contain similar or identical issues to their current counterparts. Once the main files are corrected, those changes should be propagated to versioned docs. Acceptable Passive Voice UsageThe following passive voice constructions are acceptable and should remain:
|
📚 Terminology ReviewI've reviewed all 59 changed documentation files for terminology consistency. Here's what I found: ✅ Excellent: Product NamesNo issues found! The documentation consistently uses:
|
| Category | Status | Issues Found |
|---|---|---|
| Product names | ✅ Excellent | 0 |
| Abbreviations | ✅ Good | 0 |
| Code formatting | ~300-400 | |
| Feature names | ~50-100 |
🔧 Recommendation
The main issue is missing backticks for technical terms. This affects readability and consistency across the installation and configuration documentation. Consider a systematic review of:
- All environment variable references (
TOWER_*,SEQERA_*,NXF_*) - All file name references (
docker-compose.yml,tower.yml,.env) - All path references (
/etc/,/var/,/opt/) - All configuration key references
Note: These patterns are mirrored in all three versioned doc sets (25.1, 25.2, 25.3).
🔍 Clarity ReviewI reviewed 60 documentation files for clarity issues. Here are the findings: Summary
Critical Issues by File
|
| Term | Occurrences | Should Define As |
|---|---|---|
| "compute environment" | 45 | "Configured set of resources for running pipelines" |
| "ingress controller" | 23 | "Kubernetes component managing external access" |
| "persistent volume" | 31 | "Storage that persists beyond pod lifecycle" |
| "SMTP relay" | 18 | "Email server that forwards messages" |
| "reverse proxy" | 27 | "Server forwarding requests to backends" |
| "container registry" | 34 | "Repository for storing container images" |
| "work directory" | 29 | "Directory for Nextflow temporary task files" |
Files with Most Long Sentences
install-platform.md- 12 sentences over 30 wordsplatform-helm.md- 11 sentencesoverview.md- 9 sentencesplatform-kubernetes.md- 8 sentencesconfiguration/overview.mdx- 7 sentences
Common Nominalization Issues
- "perform the configuration of" → "configure"
- "carry out the installation of" → "install"
- "make modifications to" → "modify"
- "perform the optimization of" → "optimize"
Priority Recommendations
High Priority
- Add Prerequisites sections to all installation/configuration guides
- Define key terms on first use (especially: compute environment, ingress controller, persistent volume)
- Break up sentences over 40 words in installation guides
- Convert prose lists to bullet points in install-platform.md and platform-helm.md
Medium Priority
- Simplify nominalizations throughout
- Add term definitions for Docker/Kubernetes concepts
- Restructure troubleshooting with consistent Problem/Solution format
- Add brief explanations before showing CLI commands
Low Priority
- Reduce passive voice where possible
- Simplify nested clauses in configuration examples
- Add glossary for frequently used technical terms
Versioned Documentation
The same clarity issues exist across versions 25.1, 25.2, and 25.3. When fixing current docs, apply the same fixes to versioned docs for consistency.
Files With Minimal Issues ✅
testing.md- only 2 long sentencesupgrade.md- clear structure, good readability
📝 Documentation Review Summary
Review powered by Claude Code SME agents To apply fixes: Comment |
Editorial Review - PR #1088Comprehensive editorial review of 47 documentation files (12 unique files + versioned copies across 25.1, 25.2, 25.3). Executive Summary
🔴 Critical Issues (149 total)1. "Tower" → "Seqera Platform" Rebrand (127 instances)The most critical issue across all files is the use of outdated "Tower" branding instead of "Seqera Platform". Affected Files (all versions):
Examples:
Note: Preserve "Tower" in technical contexts:
2. Third Person Usage (7 instances)Documentation uses third person ("the user", "the administrator") instead of second person ("you").
Note: These issues repeat across all versioned docs (25.1, 25.2, 25.3) 3. Complex Sentences (15 instances)Several sentences exceed 25-30 words, affecting readability. Examples: File:
File:
🟡 Important Issues (123 total)4. Missing Oxford Commas (28 instances)Lists with three or more items are missing the serial comma before "and"/"or".
Note: These issues appear across all 4 documentation versions 5. Environment Variable Formatting (34 instances)Environment variables use bold instead of backticks. File:
This issue affects ~34 environment variable references across configuration files 6. CLI Tool Formatting (15 instances)CLI tools use bold instead of code formatting.
7. Passive Voice & Future Tense (8 instances)Some sentences use passive voice or future tense instead of active voice and present tense.
8. Compute Environment Capitalization (12 instances)"Compute Environment" is capitalized when it should be lowercase (generic feature reference).
9. Unexplained Jargon (42 instances)Technical terms used without explanation or context. Examples: File:
File:
🟢 Minor Issues (228 total)10. List Punctuation Inconsistency (24 instances)Simple phrase lists inconsistently use periods at the end. File: Current:
- A container orchestration service (EKS, GKE, etc.).
- A kubectl client.
- A Helm client.
Suggested (remove periods for simple phrases):
- A container orchestration service (EKS, GKE, etc.)
- A kubectl client
- A Helm clientThis pattern appears in multiple prerequisite lists across files Recommended Action PlanPhase 1: Critical Fixes (Immediate)
Phase 2: Important Fixes (High Priority)
Phase 3: Minor Fixes (Polish)
Files Requiring Most AttentionTop 10 by Issue Count:
Review completed by Claude Code editorial agents: voice-tone, terminology, punctuation, clarity Total issues: 500 across 47 files |
justinegeffen
added
content-improvement
2 participants
this is to realign with studios and pipeline-optimization install pages which are called
/studios-docker-compose.md,/studios-kubernetes.md,/pipeline-optimization-docker-compose.md, etc while platform's were missing their prefix