Voltimax Platform

Appearance

Reviewing and Maintaining Documentation ​

Guidelines for reviewing documentation changes and keeping content current.

Pre-Merge Checklist ​

Before merging documentation changes:

  • [ ] All links work (no 404s)
  • [ ] Navigation is updated
  • [ ] Writing style matches guidelines
  • [ ] Template structure is followed
  • [ ] Prerequisites are listed
  • [ ] Build succeeds locally
  • [ ] No broken images
  • [ ] Cross-references are accurate

Review Process ​

bash
# 1. Pull the branch
git fetch
git checkout feature/new-docs

# 2. Build locally
cd docs
npm run docs:build

# 3. Preview
npm run docs:preview

# 4. Check for issues
# - Click all links
# - Verify navigation
# - Check formatting

# 5. Leave feedback or approve

Regular Maintenance ​

Monthly:

  • Review and update outdated content
  • Check for broken links
  • Update screenshots if UI changed

After Major Releases:

  • Update version numbers
  • Add release-specific guides
  • Update compatibility information
  • Archive deprecated content

When Features Change:

  • Update affected documentation immediately
  • Regenerate reference docs if schemas changed
  • Update screenshots
  • Review related cross-references

Documentation Debt ​

Track documentation issues:

bash
# Create issue for documentation updates
# Tag with "documentation" label
# Include:
# - What needs updating
# - Why it's outdated
# - Related code changes

Best Practices ​

Do ​

  • Update docs with code changes in the same PR
  • Use templates for consistency
  • Link related documentation
  • Include prerequisites
  • Provide verification steps
  • Keep sidebars organized

Don't ​

  • Skip navigation updates
  • Leave todo comments in published docs
  • Create orphan pages (not in navigation)
  • Forget to regenerate reference docs
  • Mix audience types in one document
  • Create deep folder hierarchies

Resources ​