Skip to content

docs: write user guide with GIFs showing installation, setup, and daily use #45

Description

@chernistry

Problem

Users land on the GitHub page and see code, not a product. There is no visual guide showing what RightLayout looks like, how to install it, what correction looks like in action, or how to configure settings. Without visual proof, users will not trust or install a keystroke-monitoring app.

Proposed Solution

Create docs/USER_GUIDE.md with annotated screenshots and GIF recordings.

Sections to Include

1. Installation

  • Homebrew: brew install --cask rightlayout
  • Manual: download DMG, drag to Applications
  • Include a GIF of the drag-to-Applications flow

2. Granting Accessibility Permission

  • Screenshot of System Settings > Privacy & Security > Accessibility
  • Explain WHY the permission is needed
  • Link to SECURITY.md for trust

3. First Launch

  • Screenshot of menu bar icon and dropdown
  • Explain what each menu item does

4. Your First Correction (the key demo)

  • Record a GIF showing: wrong layout active, user types, RightLayout corrects
  • This is the "aha moment" that sells the app

5. Settings

  • Screenshot of settings window
  • Explain each option (languages, launch at login, exclusions, shortcut)

6. Troubleshooting

  • "Not correcting anything" -> check Accessibility, check if paused, check exclusions
  • "Corrections are wrong" -> check layout in System Settings, report with original/expected
  • "App won't start after macOS update" -> re-grant Accessibility permission

GIF Recording Tools

  • Kap -- open source macOS screen recorder
  • LICEcap -- lightweight GIF recorder
  • gifski -- high-quality GIF encoder

Asset Storage

Store in assets/docs/:

  • install.gif -- DMG drag-to-Applications
  • accessibility.png -- System Settings permission
  • menubar.png -- Menu bar dropdown
  • correction-demo.gif -- Live correction in action
  • settings.png -- Settings window

Steps to Implement

  1. Create docs/USER_GUIDE.md with all sections
  2. Record GIFs of installation, accessibility setup, and live correction
  3. Take screenshots of menu bar and settings
  4. Save assets to assets/docs/
  5. Add prominent "User Guide" link in README
  6. Embed correction-demo.gif in README for immediate visual impact

Acceptance Criteria

  • docs/USER_GUIDE.md exists with all sections listed above
  • At least one GIF showing a live correction
  • Screenshots of menu bar and settings UI
  • Troubleshooting section covers the 3 most common issues
  • README links to the user guide
  • Guide is accessible to non-technical users

Activity

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    P4somedaydocumentationImprovements or additions to documentationgood first issueGood for newcomershacktoberfestHacktoberfest eligiblehelp wantedExtra attention is needed

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions