Skip to main content

👩‍💻 Good First Issues

Focus: Improving UX through polish, comfort, and clarity.

This app works — but it can feel better. These starter issues are designed for contributors who want to help us create a lean, elegant user experience without needing to understand every module.

🎯 Why UX Matters​

Users aren’t just running code — they’re navigating interfaces, interpreting output, and making decisions. Good UX means:

  • less friction
  • clearer mental models
  • faster iteration

These are the bridges from MVP ➝ polished product.

🧹 Starter Issues (User-Facing Polish)​

1. CLI Comfort & Messaging​

  • 🔧 Add helpful errors when --input is missing or malformed
  • 💬 Show progress through pipeline stages (e.g. "Parsing...", "Scoring...", etc.)
  • 📁 Suggest creating folders (input/, data/run_*) if not found

2. Streamlit Tab Polish​

  • 🖼️ Make links readable in results_tab.py: use job titles instead of raw URLs
  • 🔄 Auto-select newest run after completion
  • 🧭 Visual hint on query submit: spinner, confirmation, etc.
  • ✅ Show confirmation when results saved

3. Visual Guidance & Confidence​

  • 📘 Add a 📖 “Quick Help” button on each tab to explain what it's for
  • 🧪 Offer prefilled input examples ("Try this: data engineer remote")
  • 🧠 Explain key columns (e.g. recommend_apply, visa_sponsorship) with hover tooltips

4. Smart Run Naming & Aggregation​

  • 🕘 Name runs with query included, e.g. run_20250710T1300__datasci
  • 🔁 Support aggregating across runs: a view that pools scored jobs from several days
  • 📊 Add toggle to switch between compact vs detailed result views

🛠️ How to Contribute​

You don’t need to know the whole backend — just:

  1. Pick a small pain point from above
  2. Find the related script (views/, cli.py, results_tab.py)
  3. Improve clarity, guidance, or control
  4. Test with:
streamlit run jobserp_explorer/app.py

Then submit a PR or draft — small deltas welcome.

📦 Local Setup (Quick)​

python3 -m venv venv
source venv/bin/activate
pip install -e .
streamlit run jobserp_explorer/app.py

Want to work on more advanced ideas like scheduled runs, multi-user profiles, or config snapshots? Open an issue or DM the maintainer.

🙌 The best UX changes come from using the app like a real user.