Thought and Design

It’s obvious, but perhaps worth repeating, that everything raised is raised deliberately, nothing falls upward by accident. Everything the city lifts above itself has been given thought and design. Thought and design, then allotted a secretive existence, glimpsed now and again by the streetbound.

Kathleen Jamie, Findings

Vagrant shell provisioning and usernames

I’ve been spending a lot of time with the excellent Vagrant recently but was getting mildly annoyed by starting in /home/vagrant when SSHing to a box, then having to cd /vagrant to get to the shared directory each time.

I thought I’d be clever and fix this minor annoyance by adding the following line to my shell provision script:

echo 'cd /vagrant' >> ~/.bashrc

A bit of a lazy fix (as is using shell provisioning instead of Puppet or Chef) but I thought it’d get the job done and save me a few seconds.

It didn’t work, though: when I ran vagrant up and ssh’d in, I couldn’t find my edit in ~/.bashrc. When I tried manually adding the line in an ssh session it worked perfectly, though. Huh?

I realised after an embarrassingly long time that maybe Vagrant used a different username when provisioning. Sure enough, adding a quick whoami to the provision script showed root, rather than the expected vagrant. Specifying the full path in the original line worked:

echo 'cd /vagrant' >> /home/vagrant/.bashrc

So, this is basically a reminder to myself that (a) Vagrant shell provisioning scripts run as root rather than vagrant and (b) one should never make presumptions about usernames.

A personal timeline of front-end web work

I’ve been thinking about how much the process of building websites has changed since I laid down my first crappy frameset nearly fifteen years ago, so thought I’d make a quick timeline to track:

  • Significant browser releases (for context)
  • Notable techniques
  • Reading material
  • Software (editors or tools)
  • Back-end (mostly integrating into rather than developing with)

The dates refer to when I first started using something rather than the release, publication or documentation date.

1998 and before

1999

  • Internet Explorer 5.0 and Netscape Communicator 4.7
  • HTML 4.0 and tables for layout
  • HTML Goodies and Webmonkey
  • Microsoft FrontPage 98
  • Perl scripts and Microsoft Access

2000

  • Internet Explorer 5.5 and Netscape 6
  • HTML 4.01 and tables for layout
  • Dreamweaver 3 Bible
  • Dreamweaver
  • Dreamweaver templates

2001

2002

A bit of a lost year; picked up the rudiments of PHP & MySQL, rolled my own blogging thing.

2003

2004

2005

2006

2007

2008

  • Firefox 3 and Google Chrome (hurrah, rapid release cycle)
  • Rapid prototyping with UX people
  • Web Form Design
  • Bad PHP

2009

  • Internet Explorer 8.0 and Android
  • Dynamic script loaders, Modernizr and cufón
  • Even Faster Web Sites
  • Git, GitHub and VirtualBox
  • Lots of static templates managed with Subversion; still a marginally better approach than the alternatives but no one really likes this

2010

2011

2012

2013

Issue tracking basics

Some basic issue tracking concepts and tips, aimed mainly at project and account managers who may not have much experience in this area.

Always use the issue tracker

Capture all issues with a single, pre-agreed tool. Avoid reporting issues via email, IM, phone or in person.

Try to avoid other parties (eg. a client, test agency, or build partner) using another issue tracker. Having one issue tracker per project ultimately makes life easier for everyone. If this can’t be done, only allow your team access to your internal issue tracker; if you can’t find a way of automatically syncing the two systems, manually transfer tickets between that and any other systems yourself. This is not fun but will stop everyone going crazy.

Make sure everyone who’s working on the project has an account on the issue tracker and make sure they know how to use it. Don’t forget to include designers, account managers and - if politic - clients in your user list. If someone cannot or will not use the issue tracker, designate a proxy for any issues they raise. This would generally be the project or account manager.

An Excel document is not an issue tracker. If you’re using one, stop now and introduce a proper tool. Some starting points:

Simple, cheap

Agile-friendly

Powerful, expensive

Be descriptive

Make sure the description of each issue is as clear as can be. This will help prevent issues bouncing back and forth between reporters and developers, saving everyone time.

A description should cover the following:

  • Where in the project can the issue be found?
  • What steps must be taken to reproduce the issue?
  • Is the issue reproducible? That is, does it happen every time you attempt to recreate it?
  • Does the issue appear to affect one particular browser or does it affect all browsers?
  • What browser(s) are you testing with?
  • What did you expect to happen or see?
  • What would you expect to resolve the problem?

Too much information is generally better than too little information.

If the issue is visual in nature or difficult to locate, consider including an image. Capture the whole browser window rather than just the part of the page showing the issue; this can provide some handy additional context. If possible, circle the relevant area using an image editor. The built-in screen capture tools for Mac OS X and Windows will work OK, but you may find using Skitch for OS X or something similar for Windows more productive.

If the issue concerns interaction, consider including a video. If you’re using OS X, Quicktime’s screen recording will do the job well. If you’re using Windows, try one of the tools listed here.

If doing this is difficult for some reason (eg. you’re testing on a mobile device or tablet), a quick video taken with a phone can be better than no video at all.

Before submitting the issue, review the issue description and ask yourself if the developer has enough information to:

  • Reproduce the issue based on the description.
  • Know what steps should be taken to resolve the issue.

Multiple issues

Don’t conflate multiple issues in one ticket. That is, if you find yourself writing “and” in the middle of a description, think about whether what comes next is part of the issue or whether it would be better as a new issue. This makes assignment and tracking of issues much easier.

Use your judgement here. If a particular page or module has multiple typos, creating an issue for each typo would be burdensome for everyone; put them in a single ticket based on context.

Status and workflow

The priority and status fields are there for a reason. Unless you have a technical lead or developer triaging issues for you, set values for these fields and make sure everyone is working to them. However, try not to be offended if a developer changes them after reviewing the issue. The severity of an issue may not be obvious when reporting.

When changing the state of an issue (fixed, closed, reassigned etc.), add a comment outlining why this has been done.

When a bug is marked as fixed it should be assigned back to the original reporter (usually you), who should then test that the issue has been resolved and formally mark it as closed.

If the delivery date is approaching and there are still many issues to resolve, there can be pressure to close issues that may not have been addressed to everyone’s satisfaction. Don’t do this; it’ll hurt in the long run. If the delivery date can’t be pushed back, consider moving low priority issues into a post-delivery milestone and making plans to address when there’s less pressure.

Assignment

Every issue in play should have a single, designated owner. When an issue is assigned to an individual, they are responsible for making progress on that issue. If the next step is to re-assign the issue to someone else or make a request for further information, encourage people to do this as soon as possible. This helps avoid other team members becoming blocked and makes it clearer for everyone to see how much work they have left to do.

Chat tools: HipChat and Flowdock

Update 2015-08-21

Use Slack.

Update 2013-03-22

Both HipChat and Flowdock have added a bunch of new features that mean the comparison below is now a bit stale (for example, Flowdock now supports side chats and HipChat now has a native OS X app) Also, HipChat is now (optionally) free for teams of 5 users or fewer and Flowdock have been acquired By Rally Software.

Check the latest features from each before deciding. We got on very well with Flowdock during our project but in retrospect I think we would have done just as well with HipChat. They’re great services and it’s worth testing both to see which sits best with a team’s philosophy and existing tools.

I’ll revisit this next time I work on a team-based project and need to pick a chat tool.

Original post continues

We’ve been hunting for a chat tool for the project I’m currently involved in. We wanted a central space that the whole development team can use to converse that also supported automated notifications from our other tools.

Our team only has two members (do we even count as a team?) so this is massive overkill at the moment. However, we’ll be introducing more members soon and past experience suggests that adoption is faster if the system is in place before the team grows too large.

We had a few basic criteria for our chat tool:

  • Not free.
  • Not expensive.
  • Persistent chat.
  • Stable and non-buggy.
  • Supports a useful set of integrations (Github, in particular).

We came up with a shortlist and quickly discarded some possibilities:

  • Self-hosted IRC: too much effort.
  • Grove: too IRC-centric for our tastes.
  • Campfire: too 37signals.

That left two to try: HipChat and Flowdock.

Here’s a quick, very unscientific analysis of both.

HipChat

  • Supports one-to-one chats.
  • Supports guest access.
  • Looks very Atlassian (so soon after purchase, too!) This may or may not be a good thing, depending on your taste.
  • Browser (mobile and desktop), desktop, iOS and Android apps (plus SMS for the slightly mad).
    • Uses Adobe Air for the desktop app. Works fine,
    • iOS app feels solid, responsive.
  • Basic integration with other services seems solid.
    • GitHub repo integration was straightforward; no issues.
    • Doesn’t natively support atom/RSS so no easy way to hook in wiki changes. Using rss2webhook feels like a dependency too far.
  • Pasted code is indented and rendered in a monospaced font, but no language
    detection or syntax highlighting (a personal bugbear).
  • Supports @mentions.
  • Pricing is $2/mo per user: reasonable and very fair for small teams.

Flowdock

  • Doesn’t support one-to-one chats or side-chats. Could be annoying but not a disaster and may encourage small teams to keep talking together in the appropriate room.
  • Supports guest access.
  • Browser, desktop and iOS apps.
    • No SMS (not a problem) or native Android app (could be a problem).
    • Recommends Fluid for OS X.
    • Recommends Chrome App for Windows and Linux.
    • iOS app feels solid, responsive.
  • Basic integration seems solid.
    • GitHub repo integration was easy.
    • Supports Atom/RSS: very useful for wikis (Github, in this case).
  • Pasted code is indented and rendered in a monospaced font, but again no language detection or syntax highlighting. Using tab on a block of unsent text indents and triggers code formatting; a nice touch.
  • Each room comes with an associated email address; received messages are displayed in the Team Inbox with formatting and attachments preserved. Useful as a cheap integration hook and a quick way to insert information from non-Flowdock users into the space.
  • The two-pane layout was initially a little confusing.
  • Supports @mentions.
  • Tagging system looks like it could be pretty handy.
  • Pricing is currently $19/mo for 6 users (cheapest plan): more expensive than Hipchat (and we’ll most likely end up paying for unused seats) but it won’t break the bank.

Conclusion

We’re still at the early stages of our trial, with more testing to go. At the moment Flowdock is coming out slightly in front of Hipchat, despite the slightly less friendly pricing and lack of side-chats.

Thanks to Ben for acting as guinea pig during testing.