Aug 25 2016

Tools for a Hack Oregon project

Published by at 9:24 pm under KM,Technology,technology_stewardship

the-demoA Hack Oregon project is fun and you get to make a contribution. In a project like the Oregon Hunger Equation last spring, everyone is figuring out both how to have fun and collaborate during the length of the project at the same time.  The fun part means you get to improvise and invent, hang out with a bunch of cool people, figure out how your skills fit in and learn a lot.  The contribution part means you need to focus and collaborate effectively, figure out how to make what you’ve got to offer a value-add for the group and for people who use the final product — beyond the demo.

Here are some suggestions for figuring all of that out, mixing experience in a Hack Oregon project in the Spring of 2016 with technology stewardship ideas like those I wrote about “Technology Stewardship for Distributed Project Teams” (a book chapter from a few years ago that’s more theoretical).  This post is my attempt to make sense of what went on in one project and to prepare for the next one.

Some “think abouts”

  1. Nothing beats testing what works on the spot.  Forget about these suggestions if they don’t work for you or your team (even if they are based on plenty of previous experience).
  2. Working together face-to-face or side-by-side is obviously the best way to communicate. But all the other tools help make the face-to-face meetings work better because the results and the connections don’t end when everybody goes home.
  3. Like it or not, you’ll end up using a bunch of tools, some of which may be unfamiliar or unappealing to you.  This post tries to help you figure out how to use them together and which one is the best to use for which purpose.
  4. Hackathons are drop-in games: who shows up is who shows up.  People can’t make it to all the meetings and often enough they have to arrive late or leave early.  Think of how to help them get back on board with the project.  Ask them to reciprocate.
  5. People have very different styles of making sense of what’s been said or done face-to-face or via the tools the group uses.  And they remember it differently.  Figuring out how to communicate on a team is productive and can be fun, too.

    Bags of food you can buy to feed hungry people.

    Lots of different people make lots of partly-organized efforts to deal with hunger in Oregon.

  6. There are other teams working on the same or related projects. (Like you, next year.) Think of how you can make your work visible and useful to those people.  Stories are the universal way of communicating with people across time and space.
  7. Figure out what other people know and how you can help them & how they can help you.  This can’t be scheduled very well in advance, but it does happen.
  8. All the tools that the team uses need to be connected to each other.  Usually this doesn’t happen automatically; you need to post the Google Folder URL in Slack, for example.

Face-to-face meetings

Here are some suggestions for making the face-to-face meetings a solid basis for the other tools & ways of communicating.

  • Think about how to make the meetings work for you by rearranging the seating or the work tables if necessary.
  • Make it a regular thing at the beginning of each meeting to review what happened at the last meeting (or what’s happened in between).  People will remember different things.
  • Stating a session goal is useful sometimes.  Agendas are your friend.
  • Latecomers and early-leave-takers are a reality.  How can you make it easier for them?
  • When a meeting turns out to be mainly independent work sessions, it helps to spend a few minutes announcing what you’re up to at the beginning (and maybe at the end).
  • Make friends.  Remember that everybody feels like they are out of the loop.
  • Speak up when you don’t know what people are talking about.  An acronym, a work step, a source, etc., etc.  These are very complicated projects.  Nobody can know it all.  There’s always someone who feels completely out of it at a meeting.  How can you bring them in?
  • It’s good to end a meeting with a review of what people need or are working on between meetings.

collaboratingPeople directory

Starting with a simple directory of who’s working on the project, think of how you can help people connect with each other:

  • People have different handles (usernames) on different platforms — which faces, names,  nicknames, email addresses, handles, etc., go together is not obvious to someone else that needs to get in touch with you.
  • Someone needs to set up a directory that everyone can find and use from early on in the project.  People need to enter their own information for maximum accuracy and choose what they are comfortable sharing.
  • Suggested information for a people directory:
    • Name
    • Email address
    • Google ID (for edit access, etc.)
    • Phone
    • Slack, Twitter, Github, and other handles
    • Skills or roles?  Background?  Think of how other people can use or will interpret what you share about yourself.
  • Figure out how to make the directory an easy reference for everyone — especially people coming on board.

Directory of project resources

As your project grows in complexity, there are more resources that need to be coordinated.  Some people will just carry all of it in their head, but it makes a big difference to most people if there’s one document that has all the essential details.

  • Other projects or external resources might provide context that people on your project will need sooner or later.  Nobody knows all of the context, so it’s important to share.
  • A Directory of project resources could include:
    • Project goal statement
    • Slack team space URL
    • Github repository URL
    • Google Docs folder URL
    • Meeting location & time
    • People directory URL
    • A chain of custody log for the data
    • A customized version of this document?
  • Remember that project resources evolve over time, so somebody needs to update the resource directory as you go.


  • Slack is for near-real time communication.  You can think of it as a chatty project log with a long memory.
  • It runs on your phone, desktop, and the web.
  • Slack makes it easy to post and announce stuff you have to share.  It’s not such a good place for stowing resources, even though it’s easy to post stuff there.  It’s best for sharing pointers to resources.
  • On Slack, your unique identifier is your email address, not your Slack Handle, which you can change whenever you want.  It helps if your slack handle is a realistic name, not an obscure handle that’s unique, say, on Twitter or Github.  For example, “skdmknd13” might be unique and something you identify  with, but it’s not so great for conversation.  Think how odd it sounds when someone says, “Hey @skdmknd13 that was a great job!”
  • It’s easy to set up different “channels” and they can be useful to separate different parts of a project or threads of conversation, but it’s also easy to have too many of them.
  • May need to invite people joining a project on to a specific channel.  It’s nice to welcome late comers, too. It’s very useful to give new people feedback: “I see you; I see what you posted; it makes sense. Thanks.”
  • Some people use slack at work, others don’t. Response time varies according to whether people appear to be logged on or not.  Notifications by email are easy to setup and manage.

Google Docs

Google Docs is the ideal environment for storing shared text like meeting notes, references, documents, diagrams, and project rosters.  Google Spreadsheets are an effective way to keep small datasets handy.

  • Some people use Google Docs a lot and take them for granted, while others are completely mystified.  Figuring out that once they open a folder, they can add it to their own “Google Drive” turns out to be a big step in becoming comfortable with Google Docs.  Looking over each other’s shoulders to see how people use Google Docs can reveal tricks you didn’t know about or things that other people need help with.


  • If a few people can get a practice of taking notes during the beginning of a meeting, in discussions, or at the end, it will go a long way to recording important contributions and resources.  Having more than one person keep an eye on the meeting notes helps a lot so you can take turns, supply extra detail, and correct each other’s spelling.
  • A big drawback of Google Docs is that you can only search through the titles, not the contents of a document unless you open each document.  Therefore naming documents consistently and putting them into folders is really important.


  • Github is important sooner or later since version control is essential in a distributed, collaborative software development project.
  • Github can be mysterious for people who don’t use it regularly and the learning curve can seem a bit steep, despite good books that are free like Pro Git.  A little orientation at the right time helps, since people have very different skills re Github.  Without a bit of educational effort there’s a “throwing it over the transom effect” in the sense that once project activity focuses on code development, some people step back too far and ignore what’s going on.
  • Github can be a really good way to publish documentation written in Markdown, like this piece on “How to share data with a statistician.”  It’s not so good for real-time updates, but it works well when you want to leave something visible for posterity.
  • Like any tool, Github can be clumsy when used for the wrong purpose.  It’s not really a good data repository, even though it can store and display csv files.  Small datasets are better stored as a Google Spreadsheet because they can be easily sorted or filtered and readily downloaded to a csv format.
  • Depending on the size and longevity of a project issue tracking in Github can be a useful way to track bugs and manage fixes.  Using Waffle IO to visualize issues à la Trello an make issue tracking more accessible:
  • A good project is important.


  • Email is the universal fall-back communication technology (after face-to-face).
  • Some people are sensitive about sharing their email address.
  • Good for one-to-one contacts and for blasts to the team or the whole world.
  • If people have their Slack account set up correctly, Slack will send them notifications by email


  • Photos are good souvenirs and great for showing people how much fun it is — for next time.


Emily Logan, Aaron DeVore, and the whole project team contributed in one way or another to this piece.

4 responses so far

4 Responses to “Tools for a Hack Oregon project”

  1. Hi John. Good tips!

    I wish I liked google drive. I can’t fathom it at all. I don’t have that option “Add to My Drive” that you have. I do have OneDrive on my Mac Finder (same as Google Drive??). But the files and folders have nothing to do with what I have on Google Drive.

    And it’s too hard to find documents through the search etc etc.

    I’ve given up 🙁

  2. John David Smith says:

    Hi Bev. Thanks!

    “Add to My Drive” is something you have on a browser window, and you have to have logged on to

    I think OneDrive is a completely separate thing (Microsoft’s answer to Google?)…

    Part of my motivation when using Google Drive is that I really don’t want to own a file — I want to label it as common property — like you use WikiSpaces, but it allows simultaneous editing, like during a synchronous meeting. Imagine collecting goodies during a BTreat.

    Don’t give up!

Leave a Reply