Enhance entity page documentation with detailed instructions for adding Related Entities tab

[kodjomiles]

Description

Enhance entity page documentation with detailed instructions for adding Related entities tabs, including options for relation paths and JSON editing. Added examples for clarity.

Updated docs pages

Please also include the path for the updated docs

• Entities Page(/customize-pages-dashboards-and-plugins/page/entity-page#related-entities)

[notion-workspace]

Refactor section on entity relation

[aws-amplify-eu-west-1]

This pull request is automatically being deployed by Amplify Hosting (learn more).

Access this pull request here: https://pr-2677.d2ngvl90zqbob8.amplifyapp.com

[claude]

Claude finished @kodjomiles's task —— View job

---

Detailed PR Review

Todo List:

• Read CONTRIBUTING.md to understand review guidelines
• Read the modified entity-page.md file to analyze changes
• Review the changes against contributing guidelines
• Analyze existing review comments from hadar-co
• Provide detailed review feedback in markdown format

---

Review Summary

This PR enhances the Related Entities section with improved clarity and consistency. The changes are minor but improve the documentation quality according to the CONTRIBUTING.md guidelines.

✅ Positive Aspects

Style & Consistency Improvements

• Proper punctuation: Added periods to list items (lines 56-57), following CONTRIBUTING.md guideline to "End each item with a . rather than a ;"
• Consistent formatting: Improved text consistency in the tip admonition (line 62) by using lowercase and quotes
• Clearer language: Changed "dataset structure follows this shape" to "dataset follows this structure" (line 71) - more direct and clearer
• UI consistency: Added quotes around "Add tab" dialog reference (line 91) for better UI element formatting

Documentation Quality

• Accurate terminology: The changes align with Port's interface terminology by consistently referencing UI elements properly
• Maintained technical accuracy: All code examples and JSON structures remain correct
• Preserved existing content flow: The logical structure and information hierarchy are maintained

✅ CONTRIBUTING.md Compliance

The changes demonstrate good adherence to the contributing guidelines:

• Lists: Properly ends list items with periods ✓
• Consistency: Uses consistent terminology throughout ✓
• Clarity: Language is clear and straightforward ✓
• Technical accuracy: All technical information remains accurate ✓
• Formatting: Maintains consistent formatting patterns ✓

✅ Review Comments Analysis

The existing review comments from hadar-co suggest identical improvements that have already been implemented:

• Punctuation fixes for list items ✓
• Consistent terminology in tip admonition ✓
• "Dataset follows this structure" language ✓
• Proper quoting of "Add tab" dialog ✓

All suggested improvements have been successfully incorporated.

Minor Observations

1. Code examples: All JSON examples include proper showLineNumbers as required ✓
2. Headers: Proper hierarchy maintained with appropriate header levels ✓
3. Links: All internal links use full paths as required ✓
4. Tone: Maintains the appropriate technical documentation tone ✓

Recommendation

APPROVE - This PR successfully enhances the documentation quality with:

• Improved consistency and readability
• Proper adherence to style guidelines
• Maintained technical accuracy
• Clear, actionable content for users

The changes are minimal, focused, and improve the user experience without introducing any technical issues or style violations.

---

| Branch: PORTN-3395-refactor-section-on-entity-relation

[claude]

Claude finished @kodjomiles's task —— View job

---

PR Review Complete

Reviewing PR changes according to CONTRIBUTING.md guidelines:

• Read CONTRIBUTING.md for review guidelines
• Read the modified entity-page.md file
• Analyze changes against contributing standards
• Provide detailed review feedback

Review Summary

This PR significantly enhances the "Related entities" section with comprehensive documentation about adding custom Related Entities tabs. The changes are well-structured and provide valuable detail that was previously missing.

✅ Strengths

Content Quality

• Clear structure: The new content follows a logical flow from basic concepts to advanced features
• Comprehensive coverage: Documents all major features including relation paths, filters, and JSON editing
• Practical examples: Includes concrete JSON examples that users can adapt
• Good use of admonitions: The tip about relation path options is helpful and appropriately placed

CONTRIBUTING.md Compliance

• Tone & style: Uses appropriate "you" language per guidelines (entity-page.md:52, 68)
• Code formatting: All code blocks include showLineNumbers as required (entity-page.md:73, 93)
• Full path links: Images use full paths correctly (entity-page.md:42)
• List formatting: Uses - for bullets and proper punctuation (entity-page.md:56-57, 118-120)
• Clear headers: Headers follow sentence case convention

📝 Areas for Improvement

Minor Writing Issues

1. Line 114: "filters results to titles containing the letter awesome-package" - should be "containing awesome-package" (not "the letter")
2. Line 87: Could benefit from slightly more specific guidance about when JSON mode is preferred over form controls

Consistency Notes

• The existing review comments from hadar-co address some style improvements that should be incorporated
• Consider if the JSON examples could use more realistic/business-relevant property names instead of "awesome-package"

📋 Technical Accuracy

• JSON structure examples are syntactically correct
• Code examples include proper syntax highlighting
• References to other documentation pages are accurate
• The filtering logic explanation is clear and accurate

🎯 User Experience

The documentation successfully transforms what was likely a confusing feature into clear, actionable guidance. Users will be able to:

• Understand when to use "all paths" vs "specific path"
• Know how to switch between form and JSON editing modes
• Copy and adapt the provided JSON examples
• Understand the complete workflow from basic tab creation to advanced filtering

Recommendation

APPROVE - This PR significantly improves the documentation quality and user experience. The minor writing issues noted above are suggestions for future improvement rather than blocking issues. The content accurately reflects the feature capabilities and follows documentation standards.

The existing approved review from hadar-co with style suggestions should be addressed in a follow-up if desired, but they don't prevent this PR from being merged.

[claude]

Claude finished @kodjomiles's task —— View job

---

Comprehensive PR Review

Todo List:

• Read CONTRIBUTING.md to understand review guidelines
• Read the modified file to understand the changes
• Analyze changes for quality, accuracy, and adherence to guidelines
• Consider existing review comments and suggestions
• Provide comprehensive review feedback

---

Review Summary

This PR significantly enhances the "Related entities" section documentation on the entity page with comprehensive details about adding custom tabs, filtering, and JSON editing. The changes align well with Port's documentation standards and provide valuable user guidance.

✅ Strengths

Documentation Quality

• Comprehensive coverage: The new content thoroughly explains the entire workflow for adding Related entities tabs
• Clear structure: Well-organized with numbered steps and logical flow
• Practical examples: Includes both form-based and JSON examples that users can follow
• Technical depth: Covers advanced features like multi-hop relations, JSON mode, and filtering

Adherence to Contributing Guidelines

• Formatting standards: Properly uses showLineNumbers for code blocks ✓
• Tone consistency: Uses appropriate "we" language and second-person address ✓
• Code examples: JSON examples are complete and functional ✓
• Headers: Following lowercase formatting rules ✓
• Links: Uses proper full path links ✓

Content Organization

• Logical hierarchy: Clear progression from basic to advanced features
• User-focused: Explains both the "how" and "when" to use different options
• Contextual tips: The relation path options tip provides valuable guidance

🔧 Areas for Improvement

1. Technical Accuracy Issues

• Line 114: "filters results to titles containing the letter awesome-package" → should be "containing the text" not "the letter"

2. Minor Content Enhancements

• The JSON example could benefit from a brief explanation of what service_in_env_deployments represents in the context
• Consider adding a brief explanation of what "multi-hop" relations mean for users unfamiliar with the concept

3. Existing Review Comments Integration

The reviewer hadar-co provided several excellent suggestions that should be incorporated:

• Formatting improvements for the relation path bullet points
• Enhanced clarity for the relation path usage guidance
• Better wording for the dataset structure introduction
• Improved phrasing for the JSON Mode section

📋 Specific Recommendations

High Priority

1. Fix technical accuracy (line 114): Change "letter" to "text" or "string"
2. Implement reviewer suggestions: The approved reviewer's suggestions would significantly improve clarity

Medium Priority

1. Add context: Brief explanation of the example blueprint names used
2. Enhance accessibility: Consider adding alt text guidance for the existing image
3. Consistency check: Ensure all JSON examples follow the same formatting patterns

Low Priority

1. Cross-references: Consider adding links to related sections (e.g., blueprint configuration)
2. Troubleshooting: Could benefit from common issues/solutions section

🎯 Compliance with CONTRIBUTING.md

Guideline	Status	Notes
Headers (lowercase)	✅	All headers follow guidelines
Code examples with line numbers	✅	Both JSON blocks properly formatted
Active voice usage	✅	Clear, active instructions throughout
Concise sentences	✅	Well-structured, readable content
Consistent terminology	✅	Technical terms used consistently
Full path links	✅	Image link follows standards
Proper admonition usage	✅	Tip admonition appropriately used

🏆 Overall Assessment

This is a high-quality documentation enhancement that significantly improves user understanding of Related entities functionality. The content is comprehensive, well-structured, and follows Port's documentation standards effectively.

Recommendation: Approve with minor revisions

The changes represent a substantial improvement to the documentation. Implementing the existing reviewer's suggestions and fixing the minor technical accuracy issue would make this excellent documentation even better.

---

Branch: PORTN-3395-refactor-section-on-entity-relation
Job Run: