DanielCarter-stack commented on PR #10439:
URL: https://github.com/apache/seatunnel/pull/10439#issuecomment-3839972225
<!-- code-pr-reviewer -->
<!-- cpr:pr_reply_v2_parts {"group": "apache/seatunnel#10439", "part": 1,
"total": 1} -->
### Issue 1: Chinese and English Documentation Path Validation Not Fully
Covered (MINOR)
**Location**: Multiple files
**Issue Description**:
Although the existence of main paths has been verified, not all 67 files
have been individually verified to ensure every link target actually exists.
**Potential Risks**:
- There may be individual missing links that were not updated
- Some special anchors may not exist in the new documentation
**Impact Scope**:
- Direct impact: Documentation users
- Indirect impact: Users may encounter a small number of 404 errors
- Impact area: Individual documentation links
**Severity**: MINOR
**Improvement Suggestions**:
It is recommended to run automated link checking tools after merging:
```bash
# Install markdown-link-check
npm install -g markdown-link-check
# Check all Markdown files
find docs/ -name "*.md" -exec markdown-link-check {} \;
```
Or integrate link checking steps in CI.
---
### Issue 2: Relative Paths in Assert Sink Documentation May Cause Confusion
(MINOR)
**Location**: `docs/zh/connectors/sink/Assert.md:93`
**Change Content**:
```diff
->
定义字段值的方式与[FakeSource](../../connector-v2/source/FakeSource.md#自定义数据内容简单示例)一致。
+> 定义字段值的方式与[FakeSource](../source/FakeSource.md#自定义数据内容简单示例)一致。
```
**Issue Description**:
Referencing `../source/FakeSource.md` from
`docs/zh/connectors/sink/Assert.md` is correct, which points to
`docs/zh/connectors/source/FakeSource.md`. However, for readers unfamiliar with
the project structure, this relative path may not be intuitive enough.
**Potential Risks**:
- Documentation maintainers may mistakenly think longer relative paths
should be used
- Errors may be introduced again during documentation refactoring
**Impact Scope**:
- Direct impact: Assert Sink documentation readers
- Indirect impact: None
- Impact area: Single document
**Severity**: MINOR
**Improvement Suggestions**:
The current path is correct and no modification is needed. However, it is
recommended to clarify relative path usage conventions in the documentation
contribution guidelines.
---
### Issue 3: Lack of Automated Validation Mechanism (MINOR)
**Location**: CI/CD Process
**Issue Description**:
Currently the PR is manually checked and updated, lacking automated
mechanisms to prevent similar dead link issues from occurring again in the
future.
**Potential Risks**:
- Future documentation refactoring may introduce dead links again
- Requires continuous manual checking
**Impact Scope**:
- Direct impact: Documentation maintenance efficiency
- Indirect impact: User experience
- Impact area: Entire documentation system
**Severity**: MINOR
**Improvement Suggestions**:
Add documentation link checking steps to the CI process:
```yaml
# .github/workflows/doc-link-check.yml
name: Doc Link Check
on: [pull_request]
jobs:
check-links:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v3
- name: Check Markdown Links
uses: gaurav-nelson/github-action-markdown-link-check@v1
with:
use-quiet-mode: 'yes'
config-file: '.markdownlinkcheck.json'
```
---
### Issue 4: URL Path Case Consistency (MINOR)
**Location**: Multiple URL links
**Issue Description**:
Some GitHub blob links use mixed case (e.g., `MySQL-CDC.md`), which may
cause issues on different file systems. Although this is not an issue
introduced by this PR, it is worth noting.
**Examples**:
```markdown
https://github.com/apache/seatunnel/blob/dev/docs/en/connectors/source/MySQL-CDC.md
```
**Potential Risks**:
- May not be accessible on case-sensitive file systems
- Documentation builds on Linux servers may fail
**Impact Scope**:
- Direct impact: Users using GitHub blob links
- Indirect impact: None
- Impact area: Partial documentation
**Severity**: MINOR
**Improvement Suggestions**:
This is outside the scope of this PR, but it is recommended to unify file
naming conventions in future documentation standards to avoid mixed case.
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: [email protected]
For queries about this service, please contact Infrastructure at:
[email protected]
