Potential users are at the top of the funnel for your project. They might become users, who might use it in production, who might become paying customers, or who might become contributors.
But that means your project can't just optimize for the expert users and dedicated community members. It has to be welcoming to newcomers as well. Part 3 of this series is dedicated to the new users.
Part I – Contributors
Part II – Community
Part III – Users (you are here)
3. Make it easy for your users.
Nobel Prize winner Daniel Kahneman studied our two systems of thinking – System 1 (thinking fast) and System 2 (thinking slow). System 1 is gut reactions and first impressions. We spend most of our time in System 1, whether we like it or not.
What is the first impression when users land on your project's repository?
Practice good repository hygiene. Think of your README and repository homepage as a landing page.
Here's how to optimize your project so that users can get past System 1 and start using your project and thinking in System 2 logic.
- Keep your top-level file list short. This is a tactical one. The fewer files that are in your root directory, the less scrolling users need to do to get to your README and value proposition. It doesn't seem like much, but you have to optimize everything you can.
- Documentation should be for the latest release, not for HEAD. This is tough because you'll want to modify it in situ or in place, but this is not what users want. How often have you downloaded software only to find the API you've been following in the README is for the next version and not the one you downloaded. Worse yet, that version isn't available. So keep the subsequent documentation in the same repository but tucked away and not in the landing README.
- Stay close to semantic versioning, but don't go overboard. When building skaffold, I envisioned it as a developer tool and something you could run in CI and production for full parity. Because of this, I made sure the configuration files followed a strict semantic versioning policy. We provided an intuitive way for users to upgrade their configs, but there's a balance between stability and adding new features quickly.
- Tag and triage issues quickly. First, issues are a blessing. Someone has gone out of their way to use your product and report a bug. Treat it as one and respond quickly. Second, tag it so that you can come back to, and so that others can find it and reduce duplicated issues.
- Clear call to action in the README. Let people know if you're open to outside contributions (with an accompanying CONTRIBUTING.md possibly).
- Add multiple ways to down your software. GitHub offers a releases page where you can tag and upload binaries. This is great, but consider adding a download bucket or adding it to package managers automatically upon release. You can collect statistics from the GitHub downloads API or something like Homebrews' analytics.
- Add information like Project Goals, Anti-goals, Roadmaps, FAQs. This helps contributors know whether or not they should suggest a particular feature. In addition, it helps to formalize some of the design philosophy so that new maintainers can continue to carry on the project's spirit.
Part I – Contributors
Part II – Community
Part III – Users (you are here)