Documentation Consistency Fix Guide

Purpose: Practical guide to fix all identified consistency issues Related Docs:

STYLE-GUIDE.md - Official style standards
CONSISTENCY-AUDIT-REPORT.md - Detailed audit findings

Quick Fix Scripts

1. Update Version References (High Priority)

Problem: 240 files reference v0.9.6 instead of v0.9.8

Find affected files:

cd /Users/admin/Sites/nself/docs

# Find all v0.9.6 references
grep -r "v0\.9\.6\|0\.9\.6" . --include="*.md" | wc -l
# Result: ~240 references

# See specific files
grep -r "v0\.9\.6\|0\.9\.6" . --include="*.md" -l

Automated fix (USE WITH CAUTION):

# Backup first!
cp -r docs docs.backup

# Update version badges
find docs -name "*.md" -exec sed -i '' 's/version-0\.9\.6/version-0.9.8/g' {} \;

# Update version in links
find docs -name "*.md" -exec sed -i '' 's|releases/v0\.9\.6\.md|releases/v0.9.8.md|g' {} \;

Manual review required for:

# These may be intentional historical references:
grep -r "v0\.9\.6" docs/releases/ --include="*.md"

# Version callouts - review context
grep -r "> \*\*v0\.9\.6" docs/ --include="*.md"

Safe approach:

Update badge versions: version-0.9.6 → version-0.9.8
Update "current version" statements
Keep historical references in release notes
Change version callouts only where referring to current version

2. Fix Placeholder Inconsistencies (Medium Priority)

Problem: Mixed formats like <project-name>, PROJECT_NAME, your-project

Standard format:

Commands: <kebab-case>
Environment variables: UPPERCASE_UNDERSCORES
Examples: Use concrete values (myapp, acme)

Find mixed usage:

# Find uppercase placeholders in commands
grep -r "nself.*[A-Z_]\{5,\}" docs/commands/ --include="*.md" | head -20

# Find angle brackets with underscores
grep -r "<[A-Z_]*>" docs/ --include="*.md" | head -20

Manual fix required - Context-dependent:

Before (inconsistent):

nself tenant create PROJECT_NAME
nself tenant create <PROJECT_NAME>
nself tenant create your-project-name

After (standardized):

# In reference docs - use placeholder
nself tenant create <project-name>

# In tutorials - use concrete example
nself tenant create myapp

Recommendation: Fix file-by-file in command reference docs first.

3. Standardize Command Casing (Medium Priority)

Problem: Rare cases of NSELF, Nself, or uppercase subcommands

Find issues:

# Find wrong command casing
grep -r "NSELF db\|NSELF tenant\|Nself " docs/ --include="*.md"

# Find uppercase subcommands
grep -r "nself [A-Z][A-Z]" docs/ --include="*.md"

Expected results: Should be very few or zero

Fix:

# All commands should be lowercase:
nself db migrate up          # ✅ Correct
nself tenant create          # ✅ Correct

# NOT:
NSELF db migrate up          # ❌ Wrong
nself DB migrate up          # ❌ Wrong

4. Add Missing Language Identifiers (Low Priority)

Problem: Some code blocks missing ```bash identifier

Find blocks without language:

# Find code blocks without language identifier
grep -rn "^\`\`\`$" docs/ --include="*.md" | head -20

Fix template:

# Before:
```
nself start
```

# After:
```bash
nself start
```

Supported languages:

bash - Shell commands
sql - SQL queries
typescript, javascript, python, go - Code
json, yaml - Config files
dbml - Database markup

5. Fix Link Formats (Low Priority)

Problem: Occasional absolute paths instead of relative

Find absolute links:

# Find absolute GitHub URLs
grep -r "https://github.com/nself-org/cli/blob/main/docs" docs/ --include="*.md"

# Find absolute /docs paths
grep -r "\](/" docs/ --include="*.md"

Fix pattern:

# Wrong (absolute):
[Quick Start](getting-started/Quick-Start.md)
[Quick Start](https://github.com/.../do../getting-started/Quick-Start.md)

# Correct (relative):
# From /docs/README.md:
[Quick Start](getting-started/Quick-Start.md)

# From /docs/guides/DEPLOYMENT.md:
[Quick Start](getting-started/Quick-Start.md)

6. Standardize Headers (Low Priority)

Problem: Inconsistent capitalization (Title Case vs sentence case)

Standard: Use sentence case

✅ Correct:
# Database workflow guide
## Creating your first migration
### Migration file format

❌ Incorrect:
# Database Workflow Guide
## Creating Your First Migration
### Migration File Format

Exceptions:

Brand names: nself, PostgreSQL, Docker
Acronyms: SQL, API, CLI
Proper nouns: GitHub, Hasura

Find title case headers:

# Find headers with multiple capital words
grep -rn "^## [A-Z][a-z]* [A-Z]" docs/ --include="*.md" | head -30

Manual fix required - Review context for proper nouns.

Validation Scripts

Check Documentation Quality

Create /scripts/check-docs-consistency.sh:

#!/bin/bash

echo "=== Documentation Consistency Check ==="
echo

# 1. Check current version
CURRENT_VERSION=$(cat src/VERSION)
echo "Current version: $CURRENT_VERSION"

# 2. Find outdated version references
echo
echo "Checking for outdated version references..."
OUTDATED=$(grep -r "v0\.9\.[0-6]" docs/ --include="*.md" -l | wc -l)
echo "Files with old versions: $OUTDATED"

# 3. Check for missing language identifiers
echo
echo "Checking for code blocks without language..."
MISSING_LANG=$(grep -rn "^\`\`\`$" docs/ --include="*.md" | wc -l)
echo "Code blocks without language: $MISSING_LANG"

# 4. Check for absolute links
echo
echo "Checking for absolute paths in links..."
ABS_LINKS=$(grep -r "\](/" docs/ --include="*.md" | wc -l)
echo "Absolute link paths: $ABS_LINKS"

# 5. Summary
echo
echo "=== Summary ==="
if [[ $OUTDATED -gt 0 ]] || [[ $MISSING_LANG -gt 0 ]] || [[ $ABS_LINKS -gt 0 ]]; then
  echo "⚠️  Issues found. Run individual checks above for details."
  exit 1
else
  echo "✅ All checks passed!"
  exit 0
fi

Usage:

chmod +x scripts/check-docs-consistency.sh
./scripts/check-docs-consistency.sh

Pre-Commit Hook

Add to .git/hooks/pre-commit:

#!/bin/bash

# Check if any .md files are being committed
MD_FILES=$(git diff --cached --name-only --diff-filter=ACM | grep '\.md$')

if [ -n "$MD_FILES" ]; then
  echo "Checking documentation consistency..."

  # Check for common issues
  for file in $MD_FILES; do
    # Check for code blocks without language
    if grep -q "^\`\`\`$" "$file"; then
      echo "⚠️  Warning: $file has code blocks without language identifier"
    fi

    # Check for absolute paths
    if grep -q "\](/" "$file"; then
      echo "⚠️  Warning: $file contains absolute /docs/ paths"
    fi
  done

  echo "✅ Documentation checks complete"
fi

CI/CD Integration

Add to .github/workflows/docs-check.yml:

name: Documentation Checks

on:
  pull_request:
    paths:
      - 'docs/**/*.md'

jobs:
  check-consistency:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3

      - name: Check documentation consistency
        run: |
          # Check for outdated versions
          CURRENT_VERSION=$(cat src/VERSION)
          echo "Current version: $CURRENT_VERSION"

          # Find old version references (may be historical - warn only)
          OLD_REFS=$(grep -r "v0\.9\.[0-6]" docs/ --include="*.md" -l | wc -l)
          if [ $OLD_REFS -gt 0 ]; then
            echo "::warning::Found $OLD_REFS files with older version references"
          fi

          # Check for missing language identifiers
          MISSING=$(grep -rn "^\`\`\`$" docs/ --include="*.md" | wc -l)
          if [ $MISSING -gt 0 ]; then
            echo "::error::Found $MISSING code blocks without language identifier"
            exit 1
          fi

          echo "✅ Documentation checks passed"

Safe Update Workflow

For Major Version Updates

# 1. Backup
cp -r docs docs.backup.$(date +%Y%m%d)

# 2. Update version file
echo "0.9.8" > src/VERSION

# 3. Update badges in main docs
find docs -name "README.md" -o -name "INDEX.md" | while read file; do
  sed -i '' 's/version-0\.9\.6/version-0.9.8/g' "$file"
done

# 4. Update version tables
# (Manual - in docs/README.md and release notes)

# 5. Verify
./scripts/check-docs-consistency.sh

# 6. Review changes
git diff docs/

# 7. Commit
git add docs/
git commit -m "docs: update to version 0.9.8"

Priority Action Plan

Week 1 - Critical Updates

✅ DONE: Updated main README.md to v0.9.8
✅ DONE: Updated Quick-Start.md version notes
TODO: Review and update all INDEX.md files
TODO: Update version badges in key docs
TODO: Create check script

Week 2 - Standardization

TODO: Fix placeholder inconsistencies in command docs
TODO: Add missing language identifiers
TODO: Standardize header capitalization

Week 3 - Automation

TODO: Add pre-commit hook
TODO: Add CI/CD checks
TODO: Create contributor guidelines

Files Already Updated

✅ Completed (January 31, 2026)

/docs/README.md
- Version badge: 0.9.6 → 0.9.8
- Version callout: v0.9.6 → v0.9.8
- Version history table: Added v0.9.7 and v0.9.8
- Footer date: Updated to January 31, 2026
/do../getting-started/Quick-Start.md
- Version note: v0.9.6 → v0.9.7+ (for historical accuracy)
NEW FILES CREATED:
- /docs/STYLE-GUIDE.md - Official style standards
- /docs/CONSISTENCY-AUDIT-REPORT.md - Detailed audit
- /docs/CONSISTENCY-FIX-GUIDE.md - This file

Remaining High-Priority Files

Need Review (Version Updates)

Check these files for version references:

# Find all files with version references
grep -rl "v0\.9\.6" docs/ --include="*.md" | sort

# Prioritize:
# 1. INDEX.md files
# 2. README.md files
# 3. Getting started guides
# 4. Release notes (keep historical references)

Notes

Historical References: Don't change version numbers in release notes or historical documentation - those are intentionally dated.
Version Callouts: Only update > **v0.9.6:** notes if they refer to "current version". If they're historical ("In v0.9.6, we added..."), keep them.
Concrete Examples: When standardizing placeholders, prefer concrete examples in tutorials and guides. Save <placeholders> for reference documentation.
Test Before Commit: Always review changes with git diff before committing mass updates.
Gradual Updates: Don't feel pressured to fix everything at once. Prioritize:
- High: Version updates, broken links
- Medium: Placeholder consistency, command formatting
- Low: Header capitalization, code block languages

Quick Reference

Current Version: 0.9.8 (as of February 16, 2026)

Style Standards: See STYLE-GUIDE.md

Audit Report: See CONSISTENCY-AUDIT-REPORT.md

Documentation Consistency Fix Guide

Practical steps to standardize 406 markdown files

CONSISTENCY FIX GUIDE - nself-org/cli GitHub Wiki

Documentation Consistency Fix Guide

Quick Fix Scripts

1. Update Version References (High Priority)

2. Fix Placeholder Inconsistencies (Medium Priority)

3. Standardize Command Casing (Medium Priority)

4. Add Missing Language Identifiers (Low Priority)

5. Fix Link Formats (Low Priority)

6. Standardize Headers (Low Priority)

Validation Scripts

Check Documentation Quality

Pre-Commit Hook

CI/CD Integration

Safe Update Workflow

For Major Version Updates

Priority Action Plan

Week 1 - Critical Updates

Week 2 - Standardization

Week 3 - Automation

Files Already Updated

✅ Completed (January 31, 2026)

Remaining High-Priority Files

Need Review (Version Updates)

Notes

Quick Reference

⚠️ GitHub.com Fallback ⚠️

CONSISTENCY FIX GUIDE - nself-org/cli GitHub Wiki

Documentation Consistency Fix Guide

Quick Fix Scripts

1. Update Version References (High Priority)

2. Fix Placeholder Inconsistencies (Medium Priority)

3. Standardize Command Casing (Medium Priority)

4. Add Missing Language Identifiers (Low Priority)

5. Fix Link Formats (Low Priority)

6. Standardize Headers (Low Priority)

Validation Scripts

Check Documentation Quality

Pre-Commit Hook

CI/CD Integration

Safe Update Workflow

For Major Version Updates

Priority Action Plan

Week 1 - Critical Updates

Week 2 - Standardization

Week 3 - Automation

Files Already Updated

✅ Completed (January 31, 2026)

Remaining High-Priority Files

Need Review (Version Updates)

Notes

Quick Reference

⚠️ **GitHub.com Fallback** ⚠️

⚠️ GitHub.com Fallback ⚠️