Rewrite the README around screenshots of the features that stand out

Open
#274 0 comments 0 reactions 0 assignees View on GitHub

Maintainers usually reply within 1 day

Nobody has claimed this yet.

Assessment

Difficulty
4/5
Estimated time
3-5 days
Newbie friendliness
44/100
Issue type
Documentation
Clarity
Clearly specified
Activity status
Active
Tech stack
swift
Domain
documentation

Research direction

Start with the current README and inventory its behavior, configuration, and command reference so those details can move into linked pages under docs/ without being lost. Then identify the app views and existing launch or screenshot tooling needed to capture the requested screens using a private SB_HOME seeded with fake data. Done means a concise README with the specified feature screenshots and quick start, plus a repeatable capture script and PNGs under docs/images/.

Written by the indexing model from the issue text.

Description

documentation enhancement

The README is a wall of text. It documents every behavior in long paragraphs, so a new reader can't tell what Switchboard is, why they'd want it, or how to start. It reads like a spec.

Write a README we can be proud of:

  • Open with what it is and why. One or two sentences, then a hero screenshot of the app with several sessions running.
  • Show the features that make it stand out, each with a screenshot:
    • The Inbox, with decision and permission cards you answer without opening a terminal.
    • The Board as a Kanban view of every session's PR, from In progress to Merging.
    • Group chats and Manager conversations that start and follow sessions.
    • The account menu with usage across Claude accounts.
    • Waits, notes, and the session view's side panel.
    • Live cap and fast switching between sessions.
  • Quick start: install, start a first session, and the handful of sb commands people use daily.
  • Keep the reference out of the front page. Move the detailed behavior, config keys, and command flags that the README holds today into docs/ pages, and link to them. Nothing should be lost, but the README should be short.

Screenshots:

  • Take them from the real app with realistic but non-sensitive data. Use a private SB_HOME with fake sessions, repos, and PRs, not my real sessions, so no private repo names, PR titles, or Slack text leak.
  • Use light mode, consistent window sizes, and PNGs under docs/images/. Add a script that regenerates them, such as a bin/screenshots that seeds the fake state and captures each view, so they stay current.

Apply plain, direct writing throughout.

Dominant language
Swift
Stars
0
Forks
0
Avg merge
6h 15m
Merged PRs (30d)
308

Getting set up

This project ships no dev container, Dockerfile or contributing guide, so setting up is up to you: start from its README, and see our first-contribution guide for the general steps.

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.

More from haacked/switchboard

All issues in haacked/switchboard

Similar issues

More Swift issues

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.