“You only get one chance to make a first impression,” the old saying goes. It’s cliche, but nevertheless sound, practical advice.

In the realm of open source, it can make the difference between a project that succeeds and a project that fails. That’s why making a positive first impression when you release a repo to the world is essential—at least if your motivations involve gaining users, building a community of contributors, and attracting valuable feedback.

Initial impressions

When I assumed my role as open source evangelist at Zalando in January 2016, I inherited a GitHub organizational portfolio that spanned three organizations and more than 360 repositories. A deep dive revealed that many of those repositories didn’t offer much in the way of documentation, usability (largely due to being too tightly coupled to our internal systems), or onboarding guidance for new users and contributors. Few projects included contributor guidelines, installation and configuration instructions, or offered clear insight into the project’s purpose.

As I detailed in my last post, my first impression of our repos wasn’t entirely positive. Since then, our team has made a lot of progress. We’ve set up a separate “Incubator” GitHub organization for untested projects (it also serves as an archive); revised and improved our docs; and added missing files, to name a few of our collective efforts to tell a more compelling story and create a more positive first impression. This work continues, as we iterate and edit.

As someone who spent many years working as a journalist and writer, I tend to think in terms of storytelling. Stories commonly have a beginning, middle, and an end.

At the repository level, the idea of a project “end” doesn’t square with open source’s emphasis on evolution; the hope is that a project will live on as long as possible. But some indication of where a project comes from, what it does now, and where it’s heading is extremely valuable information to share with prospective users, contributors, and peers. For that, your project needs a solid README. This means it’ll include:

• An intro paragraph (“beginning”) that offers a clear description of the project’s purpose and functionality, as well as some details about what it doesn’t do (to place it in context with other, similar projects) and if it’s proven to work in a production environment;
• A detailed “middle” that covers essential install/use/configuration information;
• An open “end that’s not really an end”—i.e., details about next steps and plans for the project, plus an invitation for others to contribute and influence project direction

At the organization level, applying basic storytelling principles is also a valuable exercise. It invites you to question whether your overall offering is coherent and consistent, so that someone who does not belong to your organization could review what you store there and click away having gained a clear picture of your OSS-related motivations and culture.

If your development team agrees to include a thorough README, maintainers file, contributors file, license file, and development status prior to making repos live, then the outcome of that decision will reflect externally that your organization values consistency and mastering the basics.

This is where adopting and adhering to a set of minimum standards can help. For example, if your development team agrees to include a thorough README, maintainers file, contributors file, license file, and development status prior to making repos live, then the outcome of that decision will reflect externally that your organization values consistency and mastering the basics.

On the other hand, if your repos lack some of these essentials, then a visitor who’s poking around your GitHub org—whether to apply for a job or some other reason—might draw negative conclusions. Maybe it’s that your org doesn’t place a high value on documentation, leaving developers to ask more questions that docs would ordinarily solve more efficiently. (And why would you not address that inefficiency?) Maybe it’s that your team is laissez faire about testing, or (in serious cases) doesn’t even care about producing quality software. Good luck using that story to persuade outside collaborators, other companies/potential adopters, and the best-of-the-best job applicants to join you.

The stories you tell

Storytelling also emerges naturally from the way you build open source software.

If your team’s projects reflect what I call a “follow the breadcrumbs” approach—”first install A, to use B, and then with A and B you can install C, etc.”—then you might have all the ingredients for a compelling project. But you’re making it really difficult for anyone to follow along. In the era of containerization, expecting peers to do a lot of legwork just to install and run your stuff seems like an unrealistic (maybe even self-entitled) ask. Is your purpose to confuse or overwhelm people, or to onboard them while providing a great user experience?

“What’s the purpose?” is the first question to ask yourself and your team before you begin writing any code. It sets the context for project development in a way that reinforces clarity and focus. In Agile development, we break down big products and features into more digestible user stories. This enables product and engineering to communicate effectively, and for engineering to accomplish the technical work required for delivering the customer experience. The standard user story format goes like this:

• As a (who) …
• I want to (do something) …
• So that I can (produce a result) …

Thinking in terms of user stories is something that anyone can learn, and open source developers should have that skill in their toolboxes. In most cases, open source product owners should be able to articulate the needs and problems a project is trying to address. If you can put yourself in the place of some similarly situated engineer working halfway around the globe (or even just down the hall), then you can solve their problem as well as yours or your team’s. That empathy increases your impact, and might lead you and your project to great places.

Scaling your story

At the organization level, offering a selection of such software projects that provide universal solutions while addressing your specific problems indicates that your team is connected and able to have a constructive dialogue with the industry at large. They’re not focusing on what’s right in front of them, but instead have the confidence, mindset, and know-how necessary for engaging in the broader world by telling compelling stories through software.

Your development practices convey a story, and that story reveals much about the values and expectations of your tech organization. Unfriendly, incomplete, or inconsistent repositories tell the world something about your standards and approach. Uniformly high-quality repositories tell a different story.

Which one would you rather read?