OpenwaterHealth / OpenwaterHealth/openlifu-python

Improve the Open-LIFU README onboarding section

Open
#461 2 comments 0 reactions 2 assignees View on GitHub

@HussainAther is already working on this.

Since Jul 21, 2026.

contribute-without-a-unit good first issue help wanted lane:docs
Dominant language
Python
Stars
27
Forks
21
Avg merge
1d 20m
Merged PRs (30d)
6

Description

What this is

The current README assumes prior context. A first-time contributor — researcher, developer, or clinician — should be able to read the top 1–2 paragraphs and know whether the project is for them, what state it's in, and where to go next.

This issue: rewrite the top section of the README (above the technical-setup material) so it answers four questions:

  1. What is Open-LIFU? (Plain language. Two sentences.)
  2. Who is this for? (One sentence per audience: developers, researchers, clinicians.)
  3. What state is the project in? (Honest about the MATLAB→Python migration, the research-only regulatory status, the active contributor count.)
  4. Where do I go next? (Three links: community hub, Discord, this repo's good-first-issues filter.)

Why this matters

The README is the front door of the technical project. Right now it skips the "is this for me?" filter, which means people who shouldn't bother bounce in confusion and people who would be great contributors bounce because they can't tell.

What to do

  1. Comment to claim.
  2. Read the existing README top to bottom.
  3. Read the linked context: our community hub, the Frontiers paper, the latest 2–3 commits to get a sense of project state.
  4. Rewrite the top section (above existing setup material) addressing the four questions above. Keep it short — 4–6 short paragraphs total.
  5. Preserve the existing technical-setup material below your new top section unchanged.
  6. Include the short-form FDA disclaimer.
  7. Submit as a PR.

Definition of done

  • Top section answers all four questions clearly.
  • Honest about project state and regulatory status.
  • Includes the short-form regulatory disclaimer.
  • Three clear "next step" links present.
  • Reviewed by a maintainer.

Skills

  • Technical writing
  • Willingness to be opinionated about what a new contributor needs to read first

Scope estimate

3–5 hours.

Helpful starting points


How to claim this issue

  1. Comment "I'd like to work on this" — we'll assign it to you.
  2. Open a draft PR within ~2 weeks of being assigned.
  3. Ask any setup questions on this issue or in our Discord #contributing channel.

Contact: community@openwater.health

By contributing, you agree to our Contributor License Agreement. (If the CLA isn't yet live when you start, we'll handle it once the flow is up.)

Contributor guide

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.