While setting up plots2 locally (non-Gitpod) as a first-time contributor,
I noticed that the README is very comprehensive but can feel overwhelming
for newcomers who just want to get the app running quickly.
The information needed to start is present, but it is spread across many
sections (Ruby versioning, database setup, Redis, webpacker, Passenger, etc.),
which makes it hard for new contributors to identify a clear entry point.
I propose adding a short section near the top of the README that includes:
- A concise “Quick Local Setup (TL;DR)” with the minimum steps to get the app running
- A “Common Gotchas for First-Time Contributors” subsection covering:
- Ruby / Node version mismatches
- Database configuration confusion (sqlite vs mysql)
- Missing dependencies (Redis, webpacker)
- Common errors encountered during initial setup and their fixes
This would not replace the existing detailed documentation, but instead
act as a guided entry point with links to the relevant sections below.
I believe this would significantly lower the barrier for first-time contributors
and reduce setup-related friction.
While setting up plots2 locally (non-Gitpod) as a first-time contributor,
I noticed that the README is very comprehensive but can feel overwhelming
for newcomers who just want to get the app running quickly.
The information needed to start is present, but it is spread across many
sections (Ruby versioning, database setup, Redis, webpacker, Passenger, etc.),
which makes it hard for new contributors to identify a clear entry point.
I propose adding a short section near the top of the README that includes:
This would not replace the existing detailed documentation, but instead
act as a guided entry point with links to the relevant sections below.
I believe this would significantly lower the barrier for first-time contributors
and reduce setup-related friction.