Laying out the foundation on a new project

Starting a new project.

You begin thinking of all the wonderful things you’re going to design and build. All the interactions and features; the in-person user testing and A/B testing; the workflows and models; the new technology stack and style guide. It is a wonderful and amazing time.

Then, just a few short weeks later, the repo is a disorganized mess of oddly named branches from various developers. The feature tickets from the sprint are filled out differently, based upon each Manager’s writing style. Pull requests range from being empty to three page novels. Folks constantly asking the whole group in Slack for the staging URLs. Standups that take longer than 10 minutes, because people like to talk. Design mockups ending in arbitrary version numbers with the word, ‘Final’ appended to it; before that too is versioned. ReplyAll emails asking for help on a bug without a screenshot, OS information, or steps to reproduce said bug. Folks being on-boarded to the project are haphazardly given random tips and resources about the project.

All of that can be avoided.

In the beginning

One of the first things a project should do is establish conventions. Specifically, writing and documenting conventions. How are we going to name branches? How are we going to write issues, commits and pull releases? How will bugs be reported? How will documentation be handled?

Easy to scan

Typically, on the projects I’m involved with, I like to make branches and issues easy to scan. I prefix both of them with either feature or bug. Issues then get a short, descriptive title; while branches are assigned the issue number, followed by the issue title or an abbreviated version. If my issue was, “Feature: allow user to upload avatar image” and it was auto-assigned the issue number of 65; the corresponding branch would be called:

feature/65-user-upload-avatar-image

This allows me to easily see what the branch does, and if I need more information, I can find the corresponding issue. I add the issue number before the title, so the branches are organized by issue number, allowing them to be scanned easier. When I commit a change, I’ll append #<issue-number> to the commit, so it appears within the issue’s history. This allows other folks on the team, or new folks, to see what has been done on this issue with a quick glance.

Pull requests should be written clearly and concisely, using the minimum amount of words to describe the problem and solution. The title should be descriptive, and relate (if not match) the respective issue title. The PR for the above example would be something similar to:

“65 - Allow User to Upload Avatar Image”
- Add form input for avatar image
- Validate image is jpg, gif or png
- Store image in S3 bucket
- Assign image to username

This allows the reviewer to quickly view what has been solved and how it was solved. The reviewer can then look through the commits to dive deeper, and give a proper review.

Track and squash bugs

Use a ticket tracking system, and not e-mail. Bugs filed via e-mail are often missing information, don’t have the proper folks cc’d to them, rushed or ignored. Use a proper system, like Github issues, Trello, Jira, etc, to track issues. These systems allow for proper category tagging, issue numbers, conversation on issue, and most importantly — the ability to share with the folks who can solve them.

Determine a convention for filing bugs. The basic information that every filed bug needs is:

• Steps to reproduce
• The operating system, browser, and device it was discovered on
• Screenshot(s) of the bug
• Severity of bug

Filing bugs is an area where over communication is certainly preferred; and if you don’t have the basics listed above, you’re going to burn time later gathering that information.

Once you have this system set in place, there will still be the occasional issue filed via e-mail. Respond politely, tell them issues via e-mail are not accepted or filed and point them towards the tracking system.

Documentation is not dead

If I had a dollar for every time I heard, “We’re Agile, we don’t need documentation” I probably wouldn’t have a car payment.

Documentation doesn’t have to go off and die in a wiki, and it doesn’t have to take form in massive paragraphs of unreadable content. Make it easy to consume. At Cantina, we have a internal Slack room for each project we work on. Any time important information is shared; client contacts, staging URLs, processes, meeting notes, test user accounts, tips and tricks for different areas of the project, etc, it gets pinned to the channel. This allows for a faster recall, a decrease in group mentions asking for repeated information, and catching new people up to speed quickly and efficiently.

On my previous project, we even used Slack as our standup area. We defined a time that everyone needed to post their standup by (it was 10:30am). In the morning post an image, title it with the current date, and have everyone add their standup as a comment with a Yesterday and Today status. This gives you a nice written record of everyone’s standups, keeps it collected by using comments, no one is pulled away from a flow of work, and we’re only using the amount of time that is needed.

Organization and Agreement

What all of this boils down to, is spending some time at the beginning of a project to agree upon conventions–and then sticking to them. Everyone is accountable and should have the ability to call others out in the respective Slack channel if they break conventions. After a week of using these conventions, it becomes second nature and call outs will decrease dramatically. These things may seem trivial at first, but after they’re adopted they allow a team to become a well oiled machine. Removing these barriers, reduces time wasted and helps improve efficiency and moral.

Try this out on your next project, and let me know what you think — @mkivikoski

Like what you read? Looking for a new job? Check out my Ideal Employment process.