Overview
After several days of testing the documentation preview feature across multiple PRs, the core functionality works well. However, I've identified two areas for improvement that would enhance the user experience.
Issues & Enhancement Requests
1. Missing Build Failure Notifications
Current Behavior: When a documentation build fails, no notification is posted to the PR.
Issue: Users have no visibility into build failures, leading to confusion about why no preview link appears.
Proposed Solution:
- Add a comment to the PR when builds fail
2. Excessive Comment Spam on Active PRs
Current Behavior: A new preview comment is posted for each commit, including commit hash details.
Issue: On PRs with frequent commits, this creates comment spam since the preview URL remains the same.
Proposed Solution:
- Use a single comment per PR that gets updated rather than creating new comments
- Remove commit hash information since the preview always reflects the latest commit, or maybe would it be possible to update original comment with each commit?
3. Unnecessary Preview Generation for Automated PRs
Current Behavior: Documentation previews are generated for all PRs, including automated ones (dependency updates, etc.).
Issue: Automated PRs typically don't modify documentation content, making preview potentially adding noise to automated workflows.
Proposed Solution:
- Skip preview generation for PRs created by automation (bots, scheduled updates, etc.)
- Implement detection based on PR author, branch naming patterns, or PR labels
- Consider adding a manual override option for cases where automated PRs do need previews
4. Missing Visual Indicator for Preview Documentation
Current Behavior: Preview documentation builds display without any visual indication that users are viewing a preview version rather than the production documentation.
Issue: Users cannot distinguish between preview and production documentation.
Proposed Solution:
- Add a prominent banner at the top of preview documentation pages
- Include clear messaging indicating this is a preview build
- Maybe add the PR number or branch information for context?
- Use distinctive styling (color/positioning) to ensure visibility without interfering with content review
Overview
After several days of testing the documentation preview feature across multiple PRs, the core functionality works well. However, I've identified two areas for improvement that would enhance the user experience.
Issues & Enhancement Requests
1. Missing Build Failure Notifications
Current Behavior: When a documentation build fails, no notification is posted to the PR.
Issue: Users have no visibility into build failures, leading to confusion about why no preview link appears.
Proposed Solution:
2. Excessive Comment Spam on Active PRs
Current Behavior: A new preview comment is posted for each commit, including commit hash details.
Issue: On PRs with frequent commits, this creates comment spam since the preview URL remains the same.
Proposed Solution:
3. Unnecessary Preview Generation for Automated PRs
Current Behavior: Documentation previews are generated for all PRs, including automated ones (dependency updates, etc.).
Issue: Automated PRs typically don't modify documentation content, making preview potentially adding noise to automated workflows.
Proposed Solution:
4. Missing Visual Indicator for Preview Documentation
Current Behavior: Preview documentation builds display without any visual indication that users are viewing a preview version rather than the production documentation.
Issue: Users cannot distinguish between preview and production documentation.
Proposed Solution: