Skip to content

docs: rework the README around a 3-step quick start - #709

Merged
bburda merged 1 commit into
mainfrom
docs/readme-brand-redesign
Oct 5, 2026
Merged

bburda merged 1 commit into
mainfrom
docs/readme-brand-redesign

Conversation

@loehub

@loehub loehub commented Oct 5, 2026 •

Copy link
Copy Markdown
Contributor

Pull Request

Summary

Reworks the README so an engineer can scan it the way GitHub READMEs are usually read, and get ros2_medkit running first.

  • Top: the selfpatch.ai logo (links to the website), a compact header, and the same badges as on main, unchanged (CI, codecov, docs, license, ROS 2 distros, Discord).
  • Short description: what it does in one paragraph, with no code changes needed.
  • Quick start in three steps: get Docker, run the existing docker run command (unchanged), then curl /api/v1/apps to see every node it found, which is never empty on a running robot, and /api/v1/faults. A green tip confirms you're done.
  • No robot at hand: a pointer to the sensor demo in selfpatch_demos, where ./inject-nan.sh makes a fault appear.
  • Extras in accordions: what a fault looks like (JSON, snapshot, rosbag), live stream and web UI, installing without Docker, troubleshooting.
  • Standard sections: How it works (one diagram), Features, Compared with standard ROS 2 diagnostics (a markdown table), Ecosystem, Documentation, Contributing, License.

Removed: the Medkit Pro panel, the marketing copy, the image panels and the demo GIF. Copy is in plain language, and no other products are named.

Images: the logo, header and diagram live in selfpatch/.github (merged in selfpatch/.github#4) and load from raw.githubusercontent.com, so this repository carries no image binaries for the README. This PR also removes the unused 15 MB docs/_static/images/medkit_hero.gif.


Issue

No linked issue. This is a docs-only rework requested by the team; no issue tracks it.


Type

  • Bug fix
  • New feature or tests
  • Breaking change
  • Documentation only

Testing

  • Rendered the README through GitHub's markdown API in a local mockup of the repository page. Checked light and dark themes and opened every accordion. No images are broken.
  • All six image URLs on raw.githubusercontent.com/selfpatch/.github/main/profile/assets/ros2_medkit/ return 200 now that Host the ros2_medkit README images next to the profile .github#4 is merged.
  • Checked the commands against the code. bringup.launch.py binds 127.0.0.1 by default, so the remote-access tip adds server_host:=0.0.0.0. Its default CORS origins already allow the web UI on localhost:3000. /diagnostics stays opt-in via enable_diagnostic_bridge:=true.
  • Checked that the docs links resolve (installation, getting started, troubleshooting, REST API reference, web UI and integration tutorials).
  • Nothing else referenced medkit_hero.gif.

Hidden anchors keep the old deep links working: #run-it-in-5-minutes and #vs-standard-ros-2-diagnostics.


Checklist

  • Breaking changes are clearly described (and announced in docs / changelog if needed)
  • Tests were added or updated if needed
  • Docs were updated if behavior or public API changed

@loehub loehub changed the title docs: redesign the README in the selfpatch.ai brand docs: rework the README around a 3-step quick start Oct 5, 2026
Make the README quick to scan for engineers and get ros2_medkit running
before anything else.

- Top: the selfpatch.ai logo, a compact header and the existing badges,
  unchanged.
- A one-paragraph description in plain language.
- Quick start in three steps: get Docker, run the existing docker command
  (unchanged), then list every node ros2_medkit found and the faults. A
  tip confirms setup is done, and a pointer to the sensor demo shows a
  fault appearing when there is no robot to hand.
- Extras in accordions: what a fault looks like, the live stream and web
  UI, installing without Docker, troubleshooting.
- Standard sections: How it works, Features, Compared with standard ROS 2
  diagnostics, Ecosystem, Documentation, Contributing, License.

The logo, header and how-it-works diagram live in selfpatch/.github
(profile/design/ros2_medkit.html) and load from raw.githubusercontent.com,
so this repository carries no image binaries for the README. Drop the
15 MB docs/_static/images/medkit_hero.gif, which nothing references any
more.
@loehub
loehub force-pushed the docs/readme-brand-redesign branch from bd26de7 to 10663cd Compare October 5, 2026 17:27
@bburda
bburda merged commit b537f9b into main Oct 5, 2026
20 checks passed
@bburda
bburda deleted the docs/readme-brand-redesign branch October 5, 2026 18:24
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants