mkrause612
cc7374899b
Per Fresh Claude Review Priority #3: Cross-link related documents. Provides: - Standard cross-link format - Implementation strategy - Priority documents - Examples and templates Gradual implementation approach - add as documents touched. Date: 2026-02-16
180 lines
4.6 KiB
Markdown
180 lines
4.6 KiB
Markdown
# Cross-Linking Guide for Firefrost Operations Manual
|
|
|
|
**Purpose:** Improve navigation by linking related documents
|
|
**Created:** February 16, 2026
|
|
**Part of:** Push to 100/100 repository health rating
|
|
|
|
---
|
|
|
|
## Why Cross-Linking Matters
|
|
|
|
**Problem:** Users must rely on DOCUMENT-INDEX to find related content
|
|
**Solution:** Documents directly link to related docs
|
|
|
|
**Benefits:**
|
|
- Faster navigation
|
|
- Discover related content naturally
|
|
- Reduce reliance on index
|
|
- Better context for readers
|
|
|
|
---
|
|
|
|
## Standard Cross-Link Format
|
|
|
|
Add "Related Documents" section near end of document (before closing):
|
|
|
|
```markdown
|
|
## Related Documents
|
|
|
|
- [Infrastructure Manifest](../core/infrastructure-manifest.md) - Server IPs and specs
|
|
- [UFW Rules Guide](../security/ufw-rules.md) - Firewall configuration
|
|
- [Deployment Checklist](deployment-checklist.md) - Pre-deployment steps
|
|
```
|
|
|
|
**Format rules:**
|
|
- Use relative paths from current document
|
|
- Include brief description (3-8 words) after hyphen
|
|
- Group by topic (infrastructure, security, deployment, etc.)
|
|
- List 3-7 most relevant docs (not exhaustive)
|
|
|
|
---
|
|
|
|
## Priority Documents for Cross-Linking
|
|
|
|
### High Priority (Do First)
|
|
- Deployment guides → infrastructure-manifest.md
|
|
- Security docs → related security procedures
|
|
- Task READMEs → deployment plans, prerequisites
|
|
- Standards docs → related standards
|
|
|
|
### Medium Priority
|
|
- Planning docs → related planning docs
|
|
- Relationship docs → consultant profiles, photos
|
|
- Archive docs → what they replaced
|
|
|
|
### Low Priority (Nice to have)
|
|
- Troubleshooting → related guides
|
|
- Reference docs → source documents
|
|
|
|
---
|
|
|
|
## Implementation Strategy
|
|
|
|
**Gradual approach:**
|
|
1. Add cross-links when touching a document (opportunistic)
|
|
2. No need to update all docs immediately
|
|
3. Focus on high-traffic docs first
|
|
4. Document cross-links in commit messages
|
|
|
|
**Example commit:**
|
|
```
|
|
Add cross-links to frostwall-protocol README
|
|
|
|
Related Documents section added with links to:
|
|
- infrastructure-manifest.md
|
|
- command-center-security README
|
|
- ufw-rules.md
|
|
|
|
Improves navigation per Fresh Claude Review Priority #3.
|
|
```
|
|
|
|
---
|
|
|
|
## Automated Cross-Link Suggestions (Future)
|
|
|
|
Potential automation:
|
|
- Script analyzes document content
|
|
- Suggests related docs based on keywords
|
|
- Generates cross-link template
|
|
- Human reviews and approves
|
|
|
|
**Script idea:**
|
|
```bash
|
|
python3 automation/suggest-cross-links.py docs/tasks/frostwall-protocol/README.md
|
|
# Output: Suggested related documents based on content analysis
|
|
```
|
|
|
|
---
|
|
|
|
## Cross-Link Validation
|
|
|
|
Link checker (`automation/check-links.py`) validates cross-links:
|
|
- Ensures targets exist
|
|
- Detects broken links
|
|
- Reports outdated references
|
|
|
|
Run before committing:
|
|
```bash
|
|
python3 automation/check-links.py --verbose
|
|
```
|
|
|
|
---
|
|
|
|
## Examples
|
|
|
|
### Example 1: Task README
|
|
|
|
```markdown
|
|
## Related Documents
|
|
|
|
**Task Documentation:**
|
|
- [Deployment Plan](deployment-plan.md) - Complete 6-phase build guide
|
|
- [Prerequisites](prerequisites.md) - Pre-deployment checklist
|
|
- [Task Documentation Standard](../../standards/task-documentation-standard.md) - Standard this follows
|
|
|
|
**Infrastructure:**
|
|
- [Infrastructure Manifest](../../core/infrastructure-manifest.md) - Server details
|
|
- [Architecture Decisions](../../reference/architecture-decisions.md) - Why we chose this approach
|
|
```
|
|
|
|
### Example 2: Deployment Guide
|
|
|
|
```markdown
|
|
## Related Documents
|
|
|
|
**Before Deployment:**
|
|
- [Prerequisites Checklist](prerequisites.md) - What you need first
|
|
- [Infrastructure Manifest](../core/infrastructure-manifest.md) - Server access details
|
|
|
|
**Related Deployments:**
|
|
- [Gitea Deployment](gitea.md) - Git server setup
|
|
- [NextCloud Deployment](nextcloud.md) - File storage setup
|
|
|
|
**Security:**
|
|
- [UFW Rules](../security/ufw-rules.md) - Firewall configuration
|
|
- [SSH Hardening](../security/ssh-hardening.md) - Secure access
|
|
```
|
|
|
|
### Example 3: Standard Document
|
|
|
|
```markdown
|
|
## Related Documents
|
|
|
|
**Other Standards:**
|
|
- [Task Documentation Standard](task-documentation-standard.md) - FFG-STD-002
|
|
- [Naming Conventions](naming-conventions.md) - File/directory naming (when created)
|
|
|
|
**Implementation Examples:**
|
|
- [Whitelist Manager Task](../tasks/whitelist-manager/) - First full implementation
|
|
- [Frostwall Protocol Task](../tasks/frostwall-protocol/) - Complex example
|
|
```
|
|
|
|
---
|
|
|
|
## Maintenance
|
|
|
|
**Ongoing:**
|
|
- Add cross-links when creating new docs
|
|
- Update links when documents move
|
|
- Remove links to deprecated docs
|
|
- Run link checker weekly
|
|
|
|
**Quarterly review:**
|
|
- Identify orphaned documents (no incoming links)
|
|
- Add missing high-value cross-links
|
|
- Verify link descriptions are accurate
|
|
|
|
---
|
|
|
|
**Fire + Frost + Foundation = Where Love Builds Legacy** 💙🔥❄️
|