Gary Haran.com

I had a really good experience last night with the Standout Jobs team. We had a hairy situation dealing with some new features. The difficulty was that we did too much magic for the end user and it simply didn’t flow from an navigation point of view.

We rarely have lengthy meetings (meaning anything lasting more than 10 minutes) but we spent close to 30 minutes last night trying to figure out the best way to implement things. In the group we had ruby guru, a design guru(more of a Design-Grammer), the CTO and I (a front end programmer).

First we determined what we weren’t doing right then looked at how other web applications approached similar features. The process we went through was very different than what you’d see in a company used to the waterfall model. One saving grace was that we didn’t have huge specifications to blindly follow. This meant we had to think and speak up about what the feature should look like. At any time we could be asked to explain why we implemented something a certain way.

Everyone on the team was open to suggestions even if it meant reviewing what others in the team had already done. Actually we know that everything we do is iterative and nothing is ever set in stone. It’s called the Agile and because this process has a name it’s easier to stand behind it.

After 30 minutes of arguing we settles on an elegant solution to our problem. We split one end-user action that did two different things at once into two separate end-user actions with each their own feedback. We changed the navigation to reflect those changes which made it clearer even for us. Though we didn’t change code during the meeting the resulting code will be easier to test. It’ll also be easier to change if we want to at this point.

A similar experience in company espousing the waterfall model will clearly result in so much red tape that most programmers would just give up and live with it. Imagine having to ask a manager to change his sacrosanct specification document. So many programmers are discouraged to even speak up in large enterprise that their improvements rarely see the light of day.

In a startup egos and job titles don’t get in the way of communication. Everyone’s input is valued and encouraged.

RubyFringe exceeds expectation. The unspace crew who initiated the conference really know how to organize one.

I’m tweeting about RubyFringe live and so are many others on my list.

Writing bug reports is not an art form but a science. If you write bug reports for your team (and yes programmers should write some) here is a short list of what your report should do.

1. Tile of a bug report: describe with a subject and a verb

The title should be a clear and concise explanation of the problem. It should include a subject and a verb.

Bad: Saving does not work.
Good: Body field does not save on submit.

Don’t limit yourself to only subject and verb when the problem only occurs in some circumstances.

Better: Body field does not save on submit when using IE 7.

2. Body of a bug report: enumerate steps to reproduce

The body of the bug report should explain what steps lead to the problem. This means that anyone reading the bug report should be able to reproduce it using only the information in the report.

Bad: [empty body]
Bad: Field body does not save.
Good: I logged on with user madcoco and typed in the usual lorem ipsum in the body field. When I hit submit the “saving” message appeared but timed-out. When I hit refresh the rest of the form was saved but not the body field. This occured using Internet Explorer 7 but worked fine in Firefox 3.

Don’t forget that as you get more information you can always append more text to the body.

Better: John Doe from SkyNet tells me that he has the same error and it seems to be related to the latest Windows Update from Microsoft. This is a known issue as seen on http://www.ie-vista.com/known_issues.html

3. Body of a bug report: support the report with screenshot or screencast

The best bug report I received was a 22 second screencast. It arrived via email from a user who used some code of mine but was really bad at English. A screenshot might be all it takes but a video is the ultimate bug report.

Happy bug squashing!

Subversion is being phased out in favor of git so if you are just starting a project I recommend you hop on the git bandwagon right away. If you are stuck on svn though and need to branch and merge here’s a quick how-to.

Branching

svn cp https://myserver.dev/project/project_name/trunk https://myserver.dev/project/project_name/branches/branch_name
cd
svn co https://myserver.dev/project/projectname/branches/branch_name
cd branch_name

Now you can do your work in the branch as you would in trunk.

Merging To The Branch

Most people like to merge from trunk to the branch to make sure that tests still run. That way if you have to do a few various fixes you can do them step by step, each with their own checkin.

In order to do so in SVN you have to know what revision you merged at. This is tedious but there is a trick that the piston creator showed me.

Run this from the folder you have your branch checked out in.

svn log --stop-on-copy https://myserver.dev/project/projectname/branches/branch_name --revision HEAD:1

Logs will appear and you just have to remember the last revision number that appears. It is preceded by a lower case r. In my case it was r555 so 555 is the important number for me.

Now still in the same branch folder take that revision number and add it to this command:

svn merge -r 555:HEAD https://myserver.dev/project/project_name/trunk

Make sure that your tests run and if you have any conflict you have to manually edit the files to resolve them. Once everything is fine you can commit your changes to the branch.

svn commit -m "merged from trunk to branch"

Merging Back To Trunk

Now you have to go back to the folder where you edit your trunk. Here you must use the revision number you used earlier. The one that determines when you branched.

svn merge -r 555:HEAD https://myserver.dev/project/projectname/branches/branch_name

Hopefully you don’t have any conflicts but if you do open each conflicting files. Edit them to your liking and then use svn resolved filename. Finish up with a commit.

So that’s it. The good news for those of you stuck with SVN their next version will make this process slightly easier. Of course I hope that before they release the new version that you’ve joined the distributed wagon.