Documentation Maintenance Roadmap

Your guide to maintaining high-quality documentation

Overview

This roadmap helps you maintain the Abrino Docs documentation site, ensuring content stays accurate, useful, and well-organized.

Daily Tasks

As You Work

  • Create new documentation for new features/processes
  • Update docs when making code/infrastructure changes
  • Fix typos and errors as you spot them
  • Answer questions by improving documentation

Using Obsidian

  1. Write - Open Obsidian, write/edit markdown files
  2. Preview - Use Obsidian’s preview to check formatting
  3. Commit - Use Obsidian Git plugin to commit
  4. Push - Push changes to GitHub
  5. Verify - Check deployed site after ~2-3 minutes

Weekly Tasks

Content Review (15 minutes)

  • Check recent documentation changes
  • Review internal docs ready for publishing
  • Update “Last Updated” dates on edited pages
  • Test code examples and commands

Quality Checks (15 minutes)

  • Check GitHub Actions build status
  • Review any build warnings or errors
  • Test site search functionality
  • Verify navigation links work

Workflow 

# Check build status
# Visit: https://github.com/Abrino-Cloud/Documentations/actions

# Test locally (optional)
cd /path/to/Documentations
bundle exec jekyll serve
# Visit: http://localhost:4000

Monthly Tasks

Content Audit (1 hour)

  • Review documentation older than 6 months
  • Update outdated screenshots and examples
  • Archive deprecated documentation
  • Check for broken external links
  • Improve pages with high bounce rates (if analytics available)

Organization Review (30 minutes)

  • Review navigation structure
  • Reorganize pages if needed (update nav_order)
  • Consolidate redundant documentation
  • Split overly long pages

Tag Management (30 minutes)

  • Review unpublished (internal) docs
  • Move ready docs from internal to publish
  • Archive outdated docs (change to archive tag)
  • Add missing category tags

Checklist 

## Monthly Review - [Date]

### Content
- [ ] Reviewed pages > 6 months old
- [ ] Updated X outdated pages
- [ ] Archived X deprecated pages
- [ ] Fixed X broken links

### Organization
- [ ] Navigation structure reviewed
- [ ] X pages reorganized
- [ ] X pages consolidated

### Tags
- [ ] X docs moved from internal to publish
- [ ] X docs archived
- [ ] Tags cleaned up

Quarterly Tasks

Major Review (2-3 hours)

  • Comprehensive content audit
  • Update writing style guide if needed
  • Review and update templates
  • Plan documentation for upcoming projects
  • Gather team feedback on documentation

Analytics & Metrics (if available)

  • Review most/least viewed pages
  • Identify gaps in documentation
  • Improve SEO for important pages
  • Check search query patterns

Infrastructure

  • Review Jekyll version and dependencies
  • Update theme if new version available
  • Test build performance
  • Review backup strategy

Tag-Based Publishing Workflow

Publishing New Documentation 

Write in Obsidian
    ↓
Add 'publish' tag
    ↓
Commit & Push (Obsidian Git)
    ↓
GitHub Actions builds
    ↓
Live on docs.abrino.cloud (2-3 min)

Managing Internal Docs 

Write draft
    ↓
Add 'internal' tag
    ↓
Commit & Push
    ↓
Available in /internal/ only
    ↓
When ready: Change to 'publish'
    ↓
Becomes public

Archiving Old Content 

Identify outdated content
    ↓
Change 'publish' to 'archive' tag
    ↓
Move to _docs/archived/ folder
    ↓
Update any links
    ↓
Commit & Push
    ↓
Moves to /archive/ section

Git Workflow

With Obsidian Git Plugin

The Obsidian Git plugin handles commits automatically or manually:

  1. Auto-commit: Set interval (e.g., every 30 min)
  2. Manual commit: Use command palette Ctrl/Cmd+P → “Git: Commit all changes”
  3. Push: Plugin auto-pushes or use “Git: Push”

Manual Git (if needed) 

cd /path/to/Documentations

# Check status
git status

# Add changes
git add _docs/new-page.md

# Commit
git commit -m "Add new Kubernetes deployment guide"

# Push
git push origin main

# If using feature branches
git checkout -b feature/new-docs
git add .
git commit -m "Add new documentation"
git push -u origin feature/new-docs
# Then create PR on GitHub

File Organization Best Practices

Directory Structure 

Documentations/
├── _docs/                    # All documentation
│   ├── _template.md         # Template (don't edit)
│   ├── devops/              # DevOps guides
│   │   ├── kubernetes/
│   │   ├── docker/
│   │   └── ci-cd/
│   ├── development/         # Development docs
│   │   ├── apis/
│   │   └── tutorials/
│   ├── security/            # Security docs
│   ├── troubleshooting/     # Troubleshooting
│   └── archived/            # Archived content
├── assets/                  # Images, CSS, JS
│   └── images/
├── index.md                 # Home page
├── archive.md               # Archive listing
├── internal.md              # Internal docs listing
├── TEMPLATE_GUIDE.md        # This guide
└── MAINTENANCE_ROADMAP.md   # Maintenance guide

Naming Conventions

  • Use kebab-case: deployment-guide.md
  • Be descriptive: kubernetes-production-deployment.md not k8s-prod.md
  • Group related files in folders
  • Keep archived files in archived/ subfolder

Troubleshooting

Build Failures

Problem: GitHub Actions build fails

Solution:

  1. Check Actions tab on GitHub
  2. Read error message
  3. Common issues:
    • Invalid YAML front matter
    • Syntax errors in markdown
    • Missing dependencies in Gemfile
  4. Fix and push again

Missing Pages

Problem: Page doesn’t appear on site

Solution:

  1. Check front matter has layout: default
  2. Verify file is in _docs/ directory
  3. Ensure page has publish tag (not internal)
  4. Check nav_exclude is not set to true
  5. Rebuild may be needed - push a small change

Styling Issues

Problem: Page looks wrong

Solution:

  1. Check Just the Docs documentation
  2. Verify front matter settings
  3. Test locally: bundle exec jekyll serve
  4. Clear browser cache

Obsidian Sync Issues

Problem: Changes not syncing

Solution:

  1. Check Obsidian Git plugin settings
  2. Manually commit and push
  3. Check git status: git status
  4. Pull remote changes: git pull origin main
  5. Resolve any conflicts

Resources

Documentation

Tools

Internal

  • Template Guide: /TEMPLATE_GUIDE.md
  • Template File: /_docs/_template.md
  • GitHub Repository: https://github.com/Abrino-Cloud/Documentations

Getting Help

Common Questions

  1. How do I create a new page?
    • Copy _docs/_template.md
    • Fill in front matter
    • Write content
    • Set publish tag
    • Commit and push
  2. How do I organize pages in the sidebar?
    • Use nav_order in front matter (lower = higher up)
    • Use parent to nest under another page
    • Use has_children: true for parent pages
  3. How do I preview before publishing?
    • Use internal tag first
    • Review on /internal/ page
    • Change to publish when ready
  4. How do I archive old content?
    • Change tag to archive
    • Move to _docs/archived/
    • Update any links
    • Push changes

Changelog

Keep track of major documentation changes:

Date Change Author
2025-10-28 Initial setup with Jekyll and Just the Docs Claude
2025-10-28 Added template and tag-based publishing Claude
2025-10-28 Created maintenance roadmap Claude

Last Updated: 2025-10-28

Questions? Open an issue on GitHub or ask the team.

Back to top

Copyright © 2025 Abrino Cloud. Built with Jekyll and Just the Docs.