At Sprintly, we have a lot of folks getting setup on the code base as we have people from the broader Quick Left group rolling on and off the project. This means that its important that getting setup with the project quickly is crucial to us, because we don’t know how long we have people to help and we want them to be as productive as possible. Besides, no one likes to spend the first day on a new project setting up your environment.
The best addition we’ve made to getting people on board with the project is the introduction of the troubleshooting.md file into the code base. As new people get setup, they inevitably run into errors like: “bundle exec foreman start returns SQSError: SQSError: 400 Bad Request” which I just pulled from our troubleshooting file. This is listed as a heading and the fix is listed in a paragraph below. This error in particular has to do with not having your configuration set up correctly, so it tells you which variables you need to set and how to regenerate those settings.
The beauty of this setup is that the barrier to contribution is very low. If you have an error, you just copy and paste that into a header then ask someone to fill in the “how to fix it” section. This ensures that we have a catalog of errors we’ve seen in practice and others can look to for guidance. We’ve managed to accrue 20 entries in 6 months we’ve had it around.
Another thing that we’re doing which is going well for us is a cleaner separation of our frontend and backend code. Sprintly has been majoritively API driven for some time, but it required some complex cookie handling code so we could make authenticated django requests. This is pretty simple if you’re working on your own server, but quite a bit harder if you’d like the ability to redirect your frontend to an alternate API server (such as testing against the staging API).
Because our backends are a bit complex and don’t change very often, we’ve added CORS API support to our API, meaning we can make authenticated API requests directly from the browser. We’ve played with this in demo apps and smaller UI features like the download CSV button. We’re recently shipped our first view in the UI which is powered entirely by a CORS enabled API endpoint: cross product mine. This has the benefit in that we can punt on all of the backend setup work. People can just direct their queries to a staging API or a local dev server that’s shared across an office.
By minimizing setup costs and writing down the tribal knowledge of what certain errors mean, we are able to help people get up to speed on Sprintly quickly. This makes our team feel more productive quicker and allows us to benefit from short bursts of developer time.
