Laying out the foundation on a new project

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
“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

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.

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

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.

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.

--

--

#UX #UI #Designer, #Developer, #Educator, #Speaker — Intro to #Development @OReillyMedia http://oreil.ly/1mI8FqY — Evolving #Web #Apps http://bit.ly/1OEyT7M

Love podcasts or audiobooks? Learn on the go with our new app.

Get the Medium app

A button that says 'Download on the App Store', and if clicked it will lead you to the iOS App store
A button that says 'Get it on, Google Play', and if clicked it will lead you to the Google Play store
Mike Kivikoski

Mike Kivikoski

#UX #UI #Designer, #Developer, #Educator, #Speaker — Intro to #Development @OReillyMedia http://oreil.ly/1mI8FqY — Evolving #Web #Apps http://bit.ly/1OEyT7M