As a software developer, it’s always important to lower the barrier to entry for developers, hobbyists, and just about any contributor interested in your projects. On a previous iteration of my blog, I spoke about the F5 Manifesto, named after the Visual Studio shortcut key for building and running your project. The post’s general idea was that any developer could get a copy of your project and start with little to no friction. Since that post, a lot has changed in the development space, especially when it comes to .NET Development. In this post, I’ll talk about how to keep your projects in line with the spirit of low friction. Here are some rules in no particular order.

Getting Started Readme

There is usually a shared context for a team of collaborators. These items go without saying for the initiated but can be confusing for the uninitiated. Starting with a clear context-defining document can help folks be on the same initial foundation getting started:

• What frameworks do I need on my machine? Node, Ruby, .NET Core, etc.
• What are some of the development environments we utilize? VS Code, Visual Studio, JetBrains Rider.
• What tooling might you need to get started? Git, GPU graphics card, or more.
• What knowledge do you need? Calculus, Statistics, or architectural philosophies.
• A clear philosophical statement of what the project is and isn’t.

Starting with a document outlining the context of expectations can help folks prepare to contribute meaningfully to the project or whether they still have work to do.

All Infrastructure Dependencies Should Be Containerized

Are you thinking about using a database, web service, or cloud infrastructure? Make sure it is distributable as a readily available container image. DockerHub is a great place to share low-friction infrastructure with anyone willing to help.

I’ve written an awesome post using docker-compose where you can get started with the containerization approach!

Consistent Build and Run Entry Points

It’s common to see a project with different build pipelines for local development, continuous integration, and other target environments. The differentiation adds unnecessary cognitive overhead for anyone looking to get started with your project. Make sure you can build the project locally.

I’ve also experienced projects with unclear starting points for developers. Do I run this npm script? Do I run a dotnet command? Do I run a bundle exec command? Make it clear where the entry point is. If you’re a .NET developer, check out my post on running node commands from your .NET project.

If you’re a .NET developer, check out my simple post on running npm scripts from your .NET Core projects. It will change how you look at setting up your polyglot projects. Also checkout my post on running Parcel from your .NET project.

Scripts, Scripts, Scripts

Think about what your project takes to get started, and then script that process. Typical tasks to script include:

• Checking environmental tool-chain like Node, .NET SDK, Ruby version. Write a script to make the installation of dependencies reproducible.
• Database seeding your initial state. If your application requires an initial dataset, create a runner to retrieve or generate that dataset.
• Third-party APIs should be stubbed whenever possible. In the absence of that possibility, retrieving tokens and secrets should be scripted as well.

In regards to scripting, keep the approaches consistent so that collaborators can enhance, extend, and evolve the scripts to meet the needs of the project.

Continuous Integration

A continuous integration pipeline is critical to any collaborative project. The shared build environment is an authority and a neutral space where all collaborators can agree on the state of the project. Does it build, or does it break? Responses of “it builds on my machine” are unacceptable in this era of modern software development.

Positive Feedback Loops

As mentioned in a previous section, with any project, there are initiated and uninitiated. It is critical to the longevity of any project to acknowledge the disparity between the knowledgable and those still learning. Create an environment designed to solicit feedback and guide contributors forward. The human components are just as critical as the technical components.

Conclusion

In 2020, we have a lot of tools at our disposal to create frictionless projects that run across multiple platforms. We first need to be explicit about the philosophical underpinnings of our project achieved through clear documentation. Utilize Docker and containerization technology to make sure contributors don’t waste hours yak shaving. For each developer, make clear the entry points for the build and execution of the application. Script every task possible whenever possible. Create technical and personal feedback loops with positive momentum in mind. And finally, have fun doing something with other folks.