SaveChm Tips: Best Practices for Archiving Compiled HTML Help
1. Prepare your CHM files
- Organize: Keep source files and final .chm in a consistent folder structure (e.g., /source, /build, /archive).
- Version: Include version numbers or dates in filenames (e.g., help_v1.2_2026-02-06.chm).
2. Verify integrity before archiving
- Open-check: Open each .chm to ensure all content, images, and links render correctly.
- Link test: Click through a representative set of pages and external links.
- Spell/format check: Run a quick spellcheck and visual pass to catch obvious issues.
3. Add metadata and documentation
- README: Include a short README with build steps, required tools (compiler versions), and source locations.
- Changelog: Add a changelog summarizing edits between versions.
- Checksums: Create and store a checksum (SHA256) for each .chm file.
4. Choose archive formats and compression
- Container: Store .chm alongside source in a compressed container (ZIP or 7z).
- Compression: Use lossless compression; 7z typically yields smaller sizes.
- Structure: Preserve directory structure inside the archive for reproducibility.
5. Preserve build environment
- Tool versions: Record compiler/toolchain versions (e.g., HTML Help Workshop version).
- Scripts: Include build scripts and any configuration files used to generate the CHM.
- Virtual image (optional): For long-term reproducibility, include a small VM/container image or a Dockerfile capturing the build environment.
6. Storage strategy
- Multiple copies: Keep at least three copies: local, offsite/cloud, and archival cold storage.
- Redundancy: Use different storage providers/formats to reduce correlated risk.
- Retention policy: Define how long to keep versions and when to prune.
7. Security and access control
- Permissions: Restrict write access to archive locations; use read-only where possible.
- Encryption: Encrypt archives containing sensitive content before uploading to cloud storage.
- Audit logs: Track who archived or restored files and when.
8. Automation and CI/CD
- Automate: Integrate CHM builds and archiving into CI pipelines to reduce human error.
- Naming: Automate consistent naming (version, date, commit hash).
- Notifications: Add alerts for failed builds or archive verifications.
9. Regular verification
- Periodic checks: Recompute checksums and attempt restores on a schedule (e.g., quarterly).
- Integrity monitoring: Use automated tools to detect bit rot or corrupt archives.
10. Recovery procedures
- Restore test: Periodically perform a full restore to verify archive usability.
- Documentation: Keep step-by-step restore instructions with contact points for issues.
Table: Recommended archive layout
| Path inside archive | Purpose |
|---|---|
| /source | Original HTML, images, CSS, scripts |
| /build | Compiled .chm files |
| /scripts | Build scripts and configs |
| /docs | README, changelog, restore instructions |
| /env | Tool version notes, Dockerfile or VM image |
| /checksums | SHA256 sums for files |
Follow these practices to ensure your CHM files remain accessible, verifiable, and reproducible over time.