Wiki Automation Guide

Wiki Automation System Guide

This document explains the automated wiki synchronization system for the HMIS project.

Overview

The HMIS project now includes an automated wiki synchronization system that keeps the GitHub wiki in sync with documentation stored in the main repository. This provides a single source of truth for all documentation.

How It Works

1. Documentation Storage

• All wiki documentation is stored in docs/wiki/ directory in the main repository
• Files are organized by module (e.g., Pharmacy/, LIMS/, OPD/)
• Standard markdown format (.md files) is used

2. Automatic Synchronization

The system provides three ways to sync documentation:

A. GitHub Actions (Automatic)

• Triggers automatically when you push changes to docs/wiki/ or developer_docs/
• Works on development and master branches
• Can be manually triggered from GitHub Actions tab

B. Safe-Push Integration

• Wiki sync is built into the existing safe-push scripts
• Automatically syncs when you use scripts/safe-push.bat or scripts/safe-push.sh
• Only syncs if docs/wiki/ directory exists

C. Manual Sync Scripts

• Windows: scripts/sync-wiki.bat
• Linux/Mac: scripts/sync-wiki.sh
• Can be run manually anytime

Directory Structure

docs/
└── wiki/
    ├── README.md                          # Main wiki documentation guide
    ├── Pharmacy-Issue.md                  # Main pharmacy issue documentation
    ├── Pharmacy-Issue-Configuration.md   # Configuration guide
    ├── Wiki-Automation-Guide.md          # This file
    └── Pharmacy/
        └── README.md                      # Pharmacy module overview

Adding New Documentation

Step 1: Create Documentation Files

1. Create your markdown file in the appropriate docs/wiki/ subdirectory
2. Use kebab-case naming (e.g., new-feature-guide.md)
3. Include proper markdown headers and navigation links

Step 2: Sync Methods

Option A: Use Safe-Push (Recommended)

# Windows
scripts\safe-push.bat

# Linux/Mac  
./scripts/safe-push.sh

Option B: Manual Git Push (Auto-sync via GitHub Actions)

git add docs/wiki/
git commit -m "Add new documentation"
git push

Option C: Manual Sync Script

# Windows
scripts\sync-wiki.bat

# Linux/Mac
./scripts/sync-wiki.sh

Step 3: Verify Synchronization

1. Check GitHub Actions tab for sync status
2. Visit https://github.com/hmislk/hmis/wiki
3. Verify your documentation appears correctly

Best Practices

File Organization

docs/wiki/
├── Module-Name/
│   ├── README.md              # Module overview
│   ├── feature-guide.md       # Feature-specific guides
│   └── configuration.md       # Configuration instructions
├── images/                    # Shared images
└── Module-Main-Page.md        # Top-level module page

Naming Conventions

• Files: Use kebab-case (e.g., pharmacy-issue-configuration.md)
• Images: Descriptive names (e.g., pharmacy-issue-interface.png)
• Directories: PascalCase for modules (e.g., Pharmacy/, LIMS/)

Content Guidelines

1. Headers: Use proper markdown hierarchy (#, ##, ###)
2. Links: Use absolute GitHub wiki URLs for cross-references
3. Images: Store in docs/wiki/images/ directory
4. Code Examples: Use proper code blocks with language specification

Navigation Structure

• Each module should have a main page (e.g., Pharmacy-Issue.md)
• Link to sub-pages using full GitHub wiki URLs
• Update parent pages when adding new documentation

Troubleshooting

Common Issues

1. Sync Not Working

• Check GitHub Actions tab for error details
• Verify docs/wiki/ directory exists
• Ensure files are properly committed

2. Missing Links

• Use full GitHub wiki URLs: https://github.com/hmislk/hmis/wiki/Page-Name
• Check file naming matches wiki page names

3. Permission Errors

• Ensure you have write access to the repository
• Check that GitHub token has appropriate permissions

4. Formatting Issues

• Verify markdown syntax is correct
• Use standard GitHub-flavored markdown
• Test locally with markdown preview

Manual Verification

# Check sync status
cd wiki
git log --oneline -5

# View pending changes
git status

# Force sync (if needed)
cd ..
scripts/sync-wiki.bat  # Windows
# or
./scripts/sync-wiki.sh  # Linux/Mac

Advanced Features

GitHub Actions Workflow

• File: .github/workflows/sync-wiki.yml
• Triggers: Push to docs/wiki/, manual dispatch
• Features:
  • Automatic navigation updates
  • Content validation
  • Detailed commit messages
  • Error handling and cleanup

Manual Workflow Dispatch

1. Go to GitHub Actions tab
2. Select "Sync Wiki Documentation" workflow
3. Click "Run workflow"
4. Choose "Force sync all wiki content" if needed

Developer Documentation Sync

• Files in developer_docs/ automatically sync to wiki
• Converted to Developer-* pages in wiki
• Maintains original structure and formatting

Monitoring and Maintenance

Regular Tasks

1. Weekly: Review GitHub Actions logs for any sync failures
2. Monthly: Audit wiki content for accuracy and completeness
3. Quarterly: Update automation scripts if needed

Performance Optimization

• Large image files should be optimized before adding
• Avoid frequent small commits to docs/wiki/ (batch changes)
• Use descriptive commit messages for better tracking

Backup Strategy

• Main repository serves as primary backup
• GitHub wiki repository serves as secondary backup
• GitHub Actions maintain detailed sync logs

Security Considerations

Access Control

• Only repository collaborators can modify documentation
• Wiki sync uses GitHub's built-in authentication
• All changes are tracked via git history

Content Validation

• Automatic link validation during sync
• Markdown format verification
• File size and type restrictions

Support and Updates

Getting Help

1. Check this guide for common issues
2. Review GitHub Actions logs for specific errors
3. Contact repository maintainers for advanced issues

System Updates

• Automation scripts are versioned with the main repository
• GitHub Actions workflow updates deployed automatically
• Breaking changes will be documented in commit messages

---

Related Documentation:

• HMIS Development Workflow
• Pharmacy Issue Documentation
• System Administration Guide

Last Updated: Auto-generated on each sync