Using GitHub as a notebook

Written by on

Using GitHub as a notebook isn't a new idea. We've noticed a few companies and different people doing this and it's a great idea.

Sure, you can use Evernote. It's a great product. As a developer, GitHub seems to fit perfectly into your workflow anyway - so why not use it as a notebook?

People can submit pull requests to add to it or create issues to review things. It accurately reflects your knowledge base and keeps track what you've been working on. It forces you to write your ideas out on "paper", regurgitating what you may have learned in the past few weeks.

I'm trying a few different things at the moment to see if they work out.

  • idealprojectgroup/rails-configuration-files: Anytime I have to configure something, I try to add it to this repository. You'll find things like my custom dnsmasq settings and Apache configurations.
  • idealprojectgroup/guidelines: Currently, this is serving as a place to brain dump. We're only three engineers strong and we've kept a set of unspoken standards for awhile. I'd like to get these down on paper and work toward a more "official" standard. My favorite part of this repo is THINGS-TO-READ.md. I hope to keep a high standard for it. It should serve as a place that summarizes our philosophy as an engineering team.

More great GitHub "notebook" repositories

Why you shouldn't be using Code Climate's automated refactoring

Written by on

Code Climate released its long-awaited automated refactoring tool today. Our team has been really excited and ripe with anticipation for months now. We put a premium on refactoring bad code, so this is something that's right up our alley.

I won't post any screenshots to spoil the surprise, but I am here to say you shouldn't be using Code Climate's automated refactoring tool.

Here are my top 10 reasons why:

  1. We tried to refactor a god object, but the Code Climate Refactoring Bot simply stopped believing in it.
     

  2. The Code Climate Refactoring Bot is a junior developer in regards to git. Our code base is now littered with vague commit messages like "Deleted".
     

  3. You'll miss out on the fun of shotgun surgery.
     

  4. You won't be able to name-drop "loosely-coupled" anymore.
     

  5. Red commits are good, but in this case, it just broke our code base.
     

  6. We'd like to see better branch names from the bot. You should only refer to magic when talking to your clients.
     

  7. No CoffeeScript support yet.
     

  8. We started to miss face-to-face time in our daily refactoring meetings. Plus, usually someone brings donuts. We can't get any work done when we're apart.
     

  9. I could no longer drive our team into the ground by yelling like a drill sergeant, "Refactor! Refactor! Refactor!"
     

  10. None of the above is true and you should read their blog post about the automated refactoring tool.

 

The importance of playing around

Written by on

Not everything you do has to be for a purpose.

Sometimes, it's ok to play around. It can even be helpful in the long run. You might not know why it's going to be helpful, or when, but it will come back to you - I promise.

Your life is built on past experience. What you do each day shapes your brain into what it will be tomorrow. As an engineer, you have inspiration all around you. If you read Hacker News or other blogs, it's almost a guarantee you find inspiration on a daily basis. If you walk around your apartment or clear your mind in the shower, you experience moments where your mind is free from distraction and the weight of your ever-present todo list.

That's why playing around is so powerful. Try it sometime. It's a trick to get you inspired or get you in the zone. Here are a few examples where playing around has helped our team:

Bruno, one of our developers, has been playing around with Chef.

Bruno wanted to dive into DevOps and learn Chef. EngineYard uses Chef, so we need to learn it as we go to make tweaks and setup deployment tasks. However, our team lacks quite a bit of knowledge in the Chef department (you know, setting up your own Rails application servers on AWS or Digital Ocean).

Bruno has been playing around with Chef for the last few weeks. In our weekly engineering meetings (I'll have to write a blog post about these), Bruno has been showing us what he's done. The first week he showed us how he spins up a Digital Ocean server via the command line. The next week he showed us the tools he was using to provision the server and setup all the necessary components (nginx, uwf, ssh, etc.). And just last week, he showed us how he setup Capistrano to complete the create, provision, deployment path.

We've also been wanting to build a pair programming gem (a one command pair-programming setup in vim and tmux for two people in different countries). As we were talking through his Chef experiments, we realized that Bruno had already built half of the gem. Part of the gem would provision a $5 Digital Ocean server to serve as a "meeting point" between the two remote developers.

Without somewhat playing around with Chef, we would still be without much progress on our gem.

In my free time, I've been researching Rails 4 and upgrading Tula at the same time.

We set an engineering goal for the year to move Tula to Rails 4. We'd like to take advantage of the Live Controller instead of using web sockets among other things. However, we haven't really set time aside to do it - we've had an overload of client work as of late and we've had higher priority items for Tula.

Instead of waiting until we were able to dedicate the time, I started playing around. I didn't really have a goal in mind nor a timeline of when I needed to get it done. I just wanted to see if I could get things working (at least a little bit).

So, I bumped the version of Rails to 4.0.3 to see what would happen. Of course, things started blowing up. I started reading through the Rails 4 upgrade guides and looking through the logs for deprecation warnings. We had quite a few scopes and queries causing problems due to changes in Rails 4. Since we weren't really on a timeline, that was ok - I slowly started fixing major problems.

Within a day or two, I was able to get things somewhat stable. We aren't done with the upgrade yet (I'm still spending just an hour or two at night), but we have a much better idea of where we're at and how much effort it will take. We're actually almost done.

If I hadn't started playing around, we still wouldn't know much about the Rails 4 situation with Tula.

Finally, here are some tips and ideas to think about if you want to try this:

  1. Let your mind roam free: You can play around with anything. Not everything you do has to ship to production.
  2. If you have 5 minutes, you have enough time to play around: Do you find yourself with 5-10 minutes at the end of your day, but you don't want to start your next big task? Play around.
  3. Play around when you're stuck: If your mind is stuck on a problem, free it by playing around. Go refactor something. Do something else. Come back to your problem later.

I'd love to hear how you play around. Find me on Twitter.

Better Communication: Annotating your screenshots

Written by on

We spend a lot of time talking about communication. And I mean, A LOT.

Here's why: Not a single person on our team works together, physically, in the same office.

We have a virtual office. When you combine HipChat and Basecamp, throw in some Google Hangouts, sprinkle some Skype, and tie it all together with text messages, emails, and telephones, what do you get? Our virtual office.

This is part one of a series of posts on how we communicate better everyday. We spend a lot of time looking back, deciding what's working and what isn't. Everyone chimes in. It's so crazy we even talk about how to use HipChat. It's all for a good cause though: the quest for better communication.

Communicating around a project is hard. Like I mentioned above, we're a remote team. Our clients are remote as well. We're hardly ever in the same office with them. Over the course of a few years, we've realized this:

Words alone usually suck

We use words a lot. However, oftentimes we're talking about something we're building. We're talking about a particular user experience or front-end, what the client is ultimately paying us for.

They don't care much about the backend. They trust our judgement - that's what they've hired us for. However, they do care about what they see, feel, and touch. Seeing tangible things makes them happy. It makes us happy too.

This is how we make it work. And, this is what you should be doing if your clients can't see you every day. 37signals mentions this in their latest book, Remote: Office Not Required.

Show them work often. This is the best way to chip away at a client's natural situational anxiety. Look, they're paying you big bucks for your work, and it's totally natural for them to begin feeling anxious the moment they send you the deposit. Show them what they're paying for. When they see the results of your efforts, they'll feel a lot better about the relationship.

Here's what we're trying to do about it

In an effort to get better at showing our work, we've started to annotate screenshots. Here's an example.

Selection_385.png

Take a screenshot. If you're using a tool with the capability, you can annotate, highlight certain parts of the shot, and point to things you're seeing. This gives you a reference point for things you want to discuss.

Nothing is more frustrating than having a conversation about something you can't see. Sometimes, it works, but most of the time you need a visual aid. Remember Speech 101?

Don't worry about being perfect. You aren't sharing your screenshot with millions of people. It just needs to be good enough. Does it help you solve the problem you're pointing out? If it does, you're doing a good job.

When you need something more than a screenshot, screen recordings give you added benefit. If you're using OS X, you can easily use Quicktime to start a screen recording (they're using screenshots with annotations, too!). You can even use your voice to annotate what you're seeing along the way.

We've found screenshots with annotations to be a successful experiment. I hope you try it out if you haven't already.

Looking for the tools to download so you can get started annotating your screenshots, here you go:

Podcast Episode 17: That moment is given to you by the lack of gravity

Written by on

Late last year, I decided I wanted to talk with someone who had gone though what might be the most unique human experience possible, someone who has been into outer space.

Fast forward to today where I was able to interview Astronaut Clayton Anderson, thanks to Source Sleuth - a service that finds experts for people telling stories.

Clayton and I talked about what it felt like to ride a rocket ship into outer space, the 15 year path he took to get there (including 14 years worth of rejection letters), the 5 months he spent on the international space station, how this perspective shapes ones worldview and what he's doing now as an author and public speaker.

I'm very grateful for the time Clayton gave to speak with me, and inspired by hearing his story of determination.

You can keep up with Clayton by following him on twitter at @astro_clay, checking out his facebook page at http://facebook.com/astroclay, and visiting his website at http://astroclay.com.

Listen to the show below, or subscribe to our podcast in iTunes.