Skip to content

Improve the Open-LIFU README onboarding section #461

@dblizinski

Description

@dblizinski

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.)

Metadata

Metadata

Assignees

Type

No fields configured for Task.

Projects

No projects

Milestone

No milestone

Relationships

None yet

Development

No branches or pull requests

Issue actions