Demystifying U.S. Federal and State-Level Veteran's Preference, one click at a time.
This project provides a clear, accessible, and user-friendly resource for U.S. veterans, their families, and advocates to understand eligibility for veteran's preference in public employment. The site features two primary tools: an interactive Federal Veteran's Preference Advisor and a new, comprehensive hub for State-Level Veterans' Preference Rules. All content is complemented by a wealth of informational guides, FAQs, and a glossary based directly on official U.S. government guidance.
➡️ Visit the Live Site & Advisor Tool: https://www.myvetguides.com/
Navigating the rules surrounding U.S. Veteran's Preference for public employment can be a daunting task. The official guidelines are comprehensive but can be dense and difficult to parse for specific situations. This project aims to bridge that gap.
Our Mission: To empower U.S. veterans and their advocates with intuitive tools and clear information, making the complexities of both federal and state-level veteran's preference more understandable and accessible.
What This Project Offers:
- The Federal Veteran's Preference Advisor: An interactive, step-by-step tool that guides users through a series of questions to help determine potential eligibility for different types of federal veteran's preference (0-point, 5-point, 10-point, derived, etc.).
- The State-Level Preference Hub: A new, central directory with detailed summaries of veteran's preference rules for public employment in all 50 states, Washington D.C., and Puerto Rico.
- A Comprehensive Information Hub: Detailed explanations of key concepts, specific federal appointing authorities (like VRA and VEOA), a glossary of terms, case studies, and more.
- Credible Foundation: All guidance and logic are meticulously based on official sources like the OPM Vet Guide for HR Professionals and state-level statutes and resources.
Who Is This For?
- U.S. Veterans seeking federal, state, or local government employment.
- Family members (spouses, mothers) exploring derived preference.
- Veteran Service Officers (VSOs) and advocates.
- HR professionals looking for a supplementary tool to explain preference.
- Anyone interested in understanding the intricacies of veteran's preference.
This project is more than just a single tool; it's a multi-faceted information hub.
A decision-tree style tool that simplifies complex federal eligibility criteria into a series of manageable questions.
- Visual Logic: Includes a Mermaid diagram that visually maps the entire decision flow of the Advisor tool, automatically generated by a Python script (
generate_diagram.py).
A comprehensive directory covering hiring preferences for public employment in all 50 U.S. states, Washington D.C., and Puerto Rico.
- Centralized Access: The State-Level Veterans' Preference page serves as a launchpad to individual state pages.
- Detailed Summaries: Each state page provides a breakdown of eligibility, preference types, and links to official state resources.
A rich library of content to explain key concepts and special programs:
- Frequently Asked Questions (FAQ): Answers to the most common questions about federal preference.
- Comprehensive Glossary of Terms: Clear definitions for over 70 technical terms.
- Guides on Special Appointing Authorities:
- Practical "How-To" Guides:
- Case Studies: Fictional scenarios illustrating how VRA, 5-point, and 10-point preferences work in practice.
All information is derived from official documentation like the OPM Vet Guide (a copy is in hrdocs.txt) and state government websites, ensuring accuracy and reliability.
This website and its tools are built using a combination of open-source technologies:
- Jekyll: A simple, blog-aware, static site generator.
- Ruby: The programming language Jekyll is built on.
- Bundler: Manages Ruby gem dependencies.
- Markdown: For writing content in an easy-to-read, easy-to-write plain text format.
- Python: Used for the
generate_diagram.pyscript to create the Advisor logic diagram. - Mermaid JS: For rendering the Advisor logic diagram from a text-based definition.
- HTML5 & CSS3 (SASS): For structure and styling.
- GitHub Pages: For hosting the live site.
The repository is organized to support the Jekyll static site and its content:
/advisor/: The heart of the interactive Federal preference tool. Contains dozens of Markdown files (.md) representing each step, question, or outcome in the decision tree./states/: The new hub for State-Level preference. Contains a Markdown file for each state and territory._layouts/&_sass/: Standard Jekyll directories for HTML templating and SASS/CSS styling._data/: Contains structured data, like the site's mainnavigation.yml./(Root Directory): Contains the main informational pages (faq.md,glossary.md,vra.md, etc.), the site's homepage (index.md), and configuration files.generate_diagram.py: The Python script that reads the/advisor/directory and automatically generates the visual logic map inadvisor/advisor_diagram.md.hrdocs.txt: The raw text of the OPM Vet Guide, serving as the primary source material for federal preference rules.
To run this website on your local machine for development or testing, follow these steps:
Ensure you have the following installed:
- Ruby: It's recommended to use a recent stable version (e.g., 3.x).
- Verify installation:
ruby -v
- Verify installation:
- Bundler: A Ruby gem for managing project dependencies.
- Install Bundler (if you don't have it):
gem install bundler
- Install Bundler (if you don't have it):
-
Clone the repository:
git clone https://github.com/hadcomfort/hadcomfort.github.io.git
-
Navigate to the project directory:
cd hadcomfort.github.io -
Install dependencies: This command installs Jekyll and other necessary Ruby gems as defined in the
Gemfile.bundle install
-
Serve the site: This command builds the site and starts a local web server.
bundle exec jekyll serve
Once the server is running (you'll see output like Server address: http://127.0.0.1:4000/), open your web browser and navigate to:
http://localhost:4000
Jekyll will automatically monitor most files for changes and rebuild the site. You may need to refresh your browser to see updates.
- Navigate to the Advisor Start Page.
- Read the introductory information and disclaimer.
- Answer the questions on each page by clicking the most appropriate link.
- The advisor will guide you through a series of steps leading to an assessment of potential federal veteran's preference eligibility.
- Navigate to the main State-Level Veterans' Preference page.
- Click on your state or territory from the list to view a detailed summary of its public employment preference rules.
Explore the various informational pages linked from the navigation menu:
- The FAQ answers common questions about federal preference.
- The Glossary defines key terms.
- Dedicated pages explain specific rules like VRA, VEOA, and others.
We warmly welcome contributions to enhance this resource! Your expertise and feedback can help make it even more valuable for veterans. We have detailed issue templates for bug reports, content suggestions, and feature requests to make contributing easy.
How You Can Contribute:
- Report Bugs or Suggest Enhancements: If you find an error, a point of confusion, or have an idea for improvement, please open an issue.
- Improve Content: Suggest clarifications, fix typos, or propose new FAQ/glossary entries. Help update content based on new OPM or state-level guidance.
- Enhance the Advisor Tool: Identify areas where the logic flow could be improved or suggest new paths.
- Code Contributions: Help improve the Jekyll site structure, enhance the
generate_diagram.pyscript, or improve accessibility and UI elements.
Pull Request Process:
- Fork the repository (
https://github.com/hadcomfort/hadcomfort.github.io/fork). - Create your feature branch (
git checkout -b feature/AmazingFeature). - Commit your changes (
git commit -m 'Add some AmazingFeature'). - Push to the branch (
git push origin feature/AmazingFeature). - Open a Pull Request.
Please ensure your contributions align with the project's goal of providing clear, accurate, and user-friendly information based on official sources.
Of course. I have integrated your chosen items into the existing roadmap, organizing them into logical categories for clarity. This new version is more detailed and provides a clear vision for the project's future.
Here is the updated "Roadmap" section for your README.md:
We envision several future enhancements to make this resource even better. The roadmap is organized into key areas of focus:
- Expanded Content: Cover more nuanced topics related to federal veteran's preference.
- Expand State Pages to Include Other Benefits: Go beyond just hiring preference on the state pages to add sections for education (state GI Bills), property tax exemptions, vehicle registration discounts, and recreational licenses.
- Create More Case Studies: Develop new, detailed scenarios for situations like derived preference, using VEOA for a promotion, or navigating a Reduction in Force (RIF).
- Guide to Post-Service Credentials & Certifications: Create a resource page that links to programs helping veterans get civilian credentials for their military training (e.g., USMAP, COOL) and explains how to feature them on an application.
- Section on Veterans' Preference for Overseas Federal Jobs: Detail the specific rules and considerations for veterans applying to federal positions located outside the United States.
- Enhanced User Interface: Continuously improve the visual design and user experience of the advisor and informational pages.
- Audit Trail Feature: Further develop the
advisor_audit_report.mdto provide users with a printable summary of their path through the advisor. - Interactive Map for State-Level Preference: Implement a clickable map of the U.S. where users can select a state to view its preference rules, making the section more visual and engaging.
- State-by-State Comparison Tool: Develop a simple table or tool that allows users to compare key preference metrics (e.g., points for disabled veterans) across multiple states.
- Data-Driven Content: Utilize Jekyll's
_datadirectory for managing lists (e.g., qualifying campaigns, glossary terms) to make updates easier and content more dynamic. - Community Feedback Integration: Systematically incorporate feedback from users and contributors through GitHub Issues and discussions.
- Conduct a Full Accessibility Audit (WCAG 2.1 AA): Perform a formal accessibility audit and create issues to address any found gaps in screen reader compatibility, keyboard navigation, or color contrast.
Your suggestions for the roadmap are also welcome!
This Veteran's Preference Advisor is an unofficial informational tool ONLY.
It is based on interpretation of publicly available U.S. government guidelines. While efforts have been made to ensure accuracy and faithfully represent official guidance, this tool does not constitute legal or official advice, nor does it guarantee any outcome or preference eligibility.
Eligibility for U.S. Federal and State Veteran's Preference is ultimately determined by the hiring public agency based on official documentation and current laws and regulations.
Always refer to official U.S. government resources or consult with a Veteran Service Officer (VSO) or agency HR personnel for definitive answers and assistance with your specific situation.
Official Resources:
- U.S. Office of Personnel Management (OPM) - VetGuide for HR Professionals: OPM VetGuide
- U.S. Department of Veterans Affairs (VA) - Careers and Employment: VA Careers and Employment
This project is licensed under the GPLv3 License. See the LICENSE file for full details.
- The content and logic of the Federal Veteran's Preference Advisor are heavily based on the U.S. Office of Personnel Management (OPM) Vet Guide for HR Professionals. This project aims to make that valuable public information more accessible.
- The Jekyll theme used is jekyll-theme-cayman.
- Community contributors who help improve this resource.
Thank you for your interest in and support of this project! We hope it serves as a valuable resource.