Guidelines for Hack-the-Gap Teams

README.2019.org

Hack-the-Gap 2019

Preparation for Weekend

In answer to the question: “What should I know, expect, and have prepared for the weekend?”

• The biggest thing to remember is to bring an open mind — you’ll learn new skills, tricks and maybe even a new programming language.
• A laptop, charger, and you might bring an extension cord / power strip. Make sure it is a machine you can install and run software on (some work laptops are locked down).
• Hav your favorite text editor installed. Make sure you have a modern code editor installed, lots of ppl use VSCode, Atom, Sublime. Be familiar with it.
• Have Git installed, and be familiar with it. Additional tools that make using Git easier include Github Desktop and SourceTree. Additionally, many modern code editors such as VSCode integrate with Git. You are not required to use the command line, although many people do. If you’re not familiar with using Git in a team, let your team members and a mentor know and we will help.
• Also, some people are designers or project organizer types — so having sketch, canva, trello and other tools ready to go is a big plus.
• Bring your ideas for something to build. If you have an idea to pitch, be able to quickly pitch it in 30 seconds. 🙂 If You don’t have ideas, that’s okay, there will be others with ideas whose teams you can join.
• On the first morning (Hack Day), after some welcome stuff, ideas are presented really briefly (30 seconds), voted on, and then people join teams to work on the ideas as projects.
• A lot of people will be new at this, you’re not alone, and everyone starts from basically zero. The very, very cool thing about HtG is that everyone I’ve ever met there has been absolutely super about bringing teams together.
• There will definitely come times during the event when you’ll want to quit and walk away; it’s not always easy to do this, but it’s actually a part of nearly every event, and it’s part of real life. It’s okay to be upset with the project, with the team, with the event, the important thing is talk about it, grab a mentor, work it through.
• HtG is structured way differently than other hack-a-thons in that you’re expected to disengage on Saturday, go home, and sleep.
• You don’t have to be an ace coder/developer to do this; there are roles on the team that require non-developer skills, including design, research, task organization, facilitating communication, team health and checkins, and so on, beyond development 🙂
• Your well-being is important. If you feel in any way compromised, let someone know. If you feel you might be in a position that you can’t talk to someone about an issue you may be having, arrange a signal with someone you trust.

Don’t be afraid to call on the mentors, really. We’re not going to do the work for you, but we can help you get there, give advice, answer questions, we’ll probably ask them, too.

Other things you may want to have available

• post-its, pens, highlighters
• extension cord / power strip
• batteries for your mouse, etc

Things to keep in mind during the weekend

Language Choices

• Many teams end up using React.JS; it’s the most popular Javascript framework right now. Be sure you can install and run `create-react-app` and then actually start up the app after it’s been created.
• If your team decides to implement parts of the app in different languages, figure out what you’ll need to make them talk to each other before you go off and implement the individual pieces.

Project Architecture

• If at all possible, avoid writing a back end for the project; the presentation will be almost entirely dependent on how the front end works and looks. Substitute dummy data, dummy servers, dummy APIs where ever you can.
• Similarly, avoid setting up APIs, authentication, authorization, and many other things you’d normally have to do for a real app. Unless you have people who are already deeply familiar with these things, you’re going to spend a lot of time reading, learning, testng, and debugging things which aren’t necessary for the demo. Instead fake these, just as you’d fake a back end server if at all possible.

Git

• Set up your team’s Git repository, on GitHub, Gitlab, BitBucket, etc., so that the master branch is protected, so team member cannot inadvertently push changes that overwrite other members’ changes.

• Create a Git branch for every feature you work on. Establish up front a means for reviewing, testing, and merging branches on the remote git depot.
• Make sure to communicate with your team members when branches are pushed up, merge/pull requests created, and so on, also if you’re dependent on unmerged branches when to pull them into your working repository.
• You can use GUI Git tools if those are easier for you. Everyone doesn’t have to use the same means of working with git, either, for example, some people are more comfortable using the command line, others Sourcetree. This is perfectly fine.

Setting the team expections

• During the first hack session (Saturday Morning), teams will get to know each other and talk over the big picture goals for their project
• By lunchtime on Saturday, hackers should have settled on an idea, put together a task list, and started working towards their goal
• After dinner on Saturday, hackers should mark which goals have been met and which can still be accomplished, and which ones to drop for the weekend
• By approximately 8pm Saturday, teams should be finishing up the project and start focusing on their presentation

README.2020.md

Some Guideance for teams

Last update: Time-stamp: <2020-04-12 20:13:35 tamara>

Please note this is guidance, not rules or restrictions. They're mainly a collection of things that work, or things that were missing when teams went off the rails, but they aren't intended to limit your team in doing what you want. An important feature of Hack-the-Gap is that the participants have fun and enjoy their time in the hack.

starting up

Nearly everyone thinks getting to code as soon as possible is the best way to get to the end of the hack-a-thon. But like every other human endeavour, spending time figure out who you are, what your outcomes and goals as a team are, and talking about the rules of the road you're going to follow up front will be extremely important later on when everything looks like a mess.

• get to know each other, find out what everyone wants to get out of the hackathon

• share contact info

• spend time up front thinking about the possibilities:

  • clearly state the problem you want to address
  • who are your customers?
  • what are their needs?

• figure out what general tools you'll use to communicate and share information. Some examples that teams have found helpful in that past, include:

  • slack
  • zoom
  • github / gitlab
  • google docs
  • trello

  use as many or as few as you need.

• schedule a retrospective check-in at the end of the first day, and another at the beginning of the second day for planning the day (and for each subsequent day for multi-day hacks)

people, roles, practices

• work in short sprints: as a team agree on work tasks for everyone, and schedule sync-up check-ins every couple of hours you are working

• appoint someone a product manager to keep track of which features are being built

• appoint someone a project manager to keep track of which tasks are in flight; manage the team repository

• someone should manage time, meetings, communication

• someone should manage project info, lore, learnings, repositories, artifacts

project goals

• research the space your app will occupy

  • sources of possible funding
  • user descriptions and user stories
  • data models and persistent vs transient information for your app
  • other offerings in your app's space
  • allied offerings in your app's space
  • APIs, data, other sources of info to drive your app
  • what is a compelling value proposition for your app

• designing towards a MVP (Minimum Viable Product) is a good interim goal, but the goal for the hackathon is to demonstrate your idea

  • it doesn't need to have anywhere near full functionality
  • target a demo presentation of around 5 minutes
  • think of "5 minutes, no powerpoints" for your demo (stolen from other demo-type events like MinneDemo), which basically means "show, don't tell"
  • on the other hand, if you can effectively demonstrate your app with powerpoint, that's okay, too; the point is not to talk about the app, but to show the app

out of scope for the hackathon

• if you're app is destined for a mobile device, demo it as a web page and use the chrome or firefox devtools to simulate it
• don't build a user management system; just fake logins, sessions, permissions, etc
• don't buy a domain name
• don't pick a brand new technology you want to learn that no one else on the team knows. While this might be fun, most such things have a pretty steep learning curve, and there likely won't be much support for it when you're in the crunch to demo

tools

• plan on using tools that let the entire team share and participate

  • google docs is usually great for this
  • github requires participants to have a github login to participate; it's easy to set up, but make sure eveyone is on it as part of your startup

• use tools the entire team is at least a little familiar with, or you feel willing to own entirely and be willing to support other team members in installing, configuring, and learning. Don't underestimate the amount of effort this is to you and everyone else

  • paper & pen are great visual design tools; share photos in slack

• utilize the other features of github if you choose to host a repo there:

  • wiki for information, documentation
  • issues for to do items, things to remember, future things; use it as a way to get the idea out of your way while working on something else (cf. "Getting Work Done")
  • projects if you need a tracker, although this may take a bit to set up if you haven't used it
  • create a github organization for your project, define a team of all the participants.
    • make a repo for orgname.github.io to be your project's home for documentation, notes, and capturing the lore for your effort. This can be done as you go along, or later in wrapping up
    • multiple repos might be necessary for splitting backend and frontend devwork
    • this can be a lot of work if you've collectively never done this before. If someone on the team is a git/github expert, let them build out the organization, team, etc.;

tech stack

• consider alternatives to using full-up backend databases, servers, etc.

  • e.g. if you just need to serve up JSON data via REST, try something like a local install of jsonserver. Even cheaper than that, try a static JSON file. Don't spend a lot time writing standard CRUD APIs
  • if you're a backend person and want something significantly backend to contribute, also consider writing up a cheat sheet for other team members to install and configure. Provide as much automation scripting as possible to alleviate having everyone learn how to do this in the midst of the hackathon
  • also, if you're a backender, consider contributing data models instead of a full up service; the team will need to think about how data is modeled and used even in the case of a fake db/be solution

• if you do go with a database backed back end, consider using free services that provide the needs of a backend system, such as

  • AirTable
  • Fauna or Prisma (graphql)
  • mLab (mongodb in the cloud)
  • ElephantSQL (postgresql in the cloud)
  • Netlify CMS

• consider alternatives to fully formed frontend systems

  • start with something like Gatsby or Next.js if you're going for a React-type development
  • also look at Vue.js, Nuxt Vue Framework
  • Static Site Generators such as Jekyll or Hugo
  • just using HTML & CSS is fine, too. Bootstrap can save time in coming up with page components.

• don't build a mobile native app, make a web app instead and simulate the mobile app instead

• utilize services such as Typeform, Google Forms to simplify doing info gathering for the demo

Key thing to remember: you won't generally have time to work on your tooling, vs. working on your demo, so make sure you choose something that is simple for the entire team to contribute.

alternatives for deployment

• Number 1, highly recommended for demo: your laptop
• github pages
• Netlify
• surge

additiona.2024.md

Addtionall Guidence for Hsck-The-Gap 2024

This advice comes from experience with several hackathons, and how presentatiops have gone during the final day.

Keep in mind goals of the weekend

Remember, the goal for the weekend is to present a demo of your application idea that conveys how a target user might perform tasks that matter to them.

You'll need to show:

• Who is this aop for?
• What problems the app solves for the target user?
• Typicwl workflows that direct the user - how do they solve their problem(s)?
• What is this app dependent on?
• What issues might arise in developing this app further?

Spend more of your time up front answering these quesitons before you jump into any sort of architecture or environement building.

Consider how information shows up for your users

• What does the user need to know to get their task done or problem solved?
• How will they tell the application about themselves and their information?
• What considerations might there be for privacy, security, and so on?

Consider how data flows into and out of the various parts of your application

Here's another reason to keep things very simple. You should keep the data flow needs exceedlingly simple. If you need ot show different data durring the demo, for example, have a few predefined data structures in JSON.

If you follow the advice to just focus on the views, i.e., the frontend, of the app, JSON can be easily dropped into your JavaScript code, even in the HTML pages with <script> elements. Folks that would be typically building databases can instead build these data structures to indicate the models of the application.

If your application is going to need data from another source via an API call, just emulate the data you'd want and don't spend a ton of time building an API client. It is reasonable to discuss various APIs, their costs, availability, and so on, while faking the API response for the demo if need be.

Development environments

One of the problems we've seen occur is that an application is built in parts by different team members with different operating environments. This leads to issues of integration when it comes time for the teqm to put the demo together and it won't work on the machine chosen for the demo.

This can be resolved by using common development environments for all users. This does bring up an additional issue, however: which common environment to use and how to configure or provision it? It falls into the same grey area of all technologicql solutions: using what you know isn't helpful if others don't know it, or can't use it quickly. Remember there is no time for learning technology in the hackathon time, and it really isn't the goal of the demo.

Since 2020 and 2019, shared development environments have evolved quite a lot.

For example, if you want to ensure everyone is working in the same environement, [Docker] has become a good way to ensure that. It doesn't nave a zero learning curve, however, so it might fall into the area around people needing to use what they know.

You can also look at [GitHub CodeSpaces] for another way to share development environments, but the free options are for individuals, not teams, so unless someone is already fasmiliar with this, it might not be a good option.

A newer option for shared team cloud-based development is [Gitpod], which works with [Github]. There is a very useful free tier that should be more than adequate for a weekend project.

Another great space to do shared development is [Glitch]. You can create an account for your team so you can all log in and work together. A potential downside is that all apps are public at the free tier, but this isn't so bad a downside remembering the goal for the weekend.

Amazon Web Service offers Cloud9 as a cloud-base development environement. Working with AWS in general is possibly too complicated for the weekend.

This is an ever changing target; I did a google search for 'free cloud-based development'; several review articles came back.

Setting up before the weekend

If you're coming into the hackathon with a pre-filled team and application in mind, you do have a distinct advantage in working out what your shared environment is going to be. Take good advantage of that so your team doesn't struggle with it during the hackathon hours.

Forgoing development entirely

While a lot of folks have the concept of hacking in a hackathon means writing software, a team doesn't have to do any software development if there's a non-coding way to get to the goals of the weekend and provide a non-coded demo.