Skip to content

Home

Jump to bottom
hadcomfort edited this page Jun 12, 2025 · 1 revision

Welcome to the Veterans Information Resource Wiki

Welcome! This wiki is the central hub for documentation, contribution guidelines, and technical information related to the Veterans Information Resource and its Preference Advisor tool.

Our mission is to provide a clear, accessible, and user-friendly resource for U.S. veterans and their families. This wiki supports that mission by explaining how our project works and how you can help make it better.

Quick Links & Table of Contents

🎯 Project Philosophy

Our work is guided by a few core principles:

  1. Grounded in Official Sources: The logic and content of this site are meticulously based on the official OPM Vet Guide for HR Professionals. A text version is maintained in the repository (hrdocs.txt) as our primary source of truth.
  2. Clarity and Accessibility: The primary goal is to translate complex regulations into an easy-to-navigate, step-by-step process. We prioritize clear language and a simple user experience.
  3. Transparency: We believe users and contributors should understand how the Advisor works. The Advisor Logic Diagram is automatically generated to provide a visual map of all decision paths.
  4. Community-Driven: This is an open-source project that thrives on community contributions. Whether it's fixing a typo, updating a state's rules, or improving the Advisor's logic, your input is invaluable.

👥 For Users & Veterans

If you're here to use the site or learn more about the project, here's what you need to know.

How to Use the Advisor Tool

  1. Start at the Preference Advisor Start Page.
  2. Read the question on each page carefully.
  3. Click the link that best describes your situation.
  4. Continue following the prompts until you reach a page that provides a potential eligibility outcome.

Reporting an Issue or Suggesting Content

Found a mistake, a broken link, or have an idea for new content? The best way to let us know is by opening an issue.

We have templates for everything from simple typo fixes to new content suggestions. Your feedback helps us keep the information accurate and helpful!

Disclaimer

Please remember, this is an unofficial informational tool. The final determination of veteran's preference is always made by the hiring federal agency.

🤝 For Contributors

Want to help improve the site? We welcome your contributions! Please start by reading our Contribution Guidelines.

How to Contribute

The typical workflow for contributing is:

  1. Find an issue to work on: Check out our open issues. Look for ones tagged good first issue if you're new!
  2. Fork the repository and create a new branch for your changes.
  3. Make your changes: Fix the bug, update the content, or build the new feature.
  4. Test your changes locally: Follow the Local Development Setup guide to run the site on your machine and ensure everything works.
  5. Submit a Pull Request: Use our Pull Request Template to describe your changes. We'll review it as soon as we can!

Types of Contributions We Need

  • ✍️ Content Updates: Correcting information in the Advisor, guides, or FAQ based on official sources.
  • 🐛 Bug Fixes: Fixing broken links or incorrect logic paths in the Advisor.
  • ✨ New Features: Expanding the Advisor or adding new informational guides.
  • 📖 Documentation: Improving this wiki to make it easier for others to contribute.

💻 For Developers (Technical Deep Dive)

This section provides a high-level overview of the project's technical aspects.

Local Development Setup

To run the site locally, you'll need Ruby and Bundler.

  1. Clone the repo: git clone https://github.com/hadcomfort/hadcomfort.github.io.git
  2. Navigate into the directory: cd hadcomfort.github.io
  3. Install dependencies: bundle install
  4. Run the local server: bundle exec jekyll serve
  5. Open http://localhost:4000 in your browser.

For more detailed instructions, see Local Development Setup.

Project Architecture Overview

The site is a standard Jekyll project hosted on GitHub Pages.

  • / (root): Contains primary markdown pages (index.md, faq.md, etc.), the _config.yml, and the hrdocs.txt source file.
  • /advisor/: The core of the interactive tool. Each .md file is a step in the decision tree.
  • /_layouts/: HTML templates that wrap our content.
  • /_sass/: SASS files for styling.
  • /.github/: Contains issue templates, pull request templates, and workflow files for GitHub Actions.

For a full breakdown, see Project Architecture Overview.

Key Scripts & Automation

  • generate_diagram.py: This Python script reads all the Markdown files in the /advisor/ directory, parses the links between them, and generates a Mermaid.js graph definition. This definition is written to advisor/advisor_diagram.md to visually represent the tool's logic.
  • GitHub Actions: We use automated workflows to:
    • Build and deploy the Jekyll site.
    • Check for broken links and lint Markdown files on every Pull Request.
    • Automatically run generate_diagram.py when Advisor files are changed.

See Key Scripts & Automation for more details.

Thank you for your interest in the Veterans Information Resource project! We look forward to your feedback and contributions.

Clone this wiki locally