How to Author a gHack

Developing a new gHack is a great way to get your content out to the world. Chances are if you’ve done workshops, PoCs or pilots in the past, you already have the material on which to build a gHack.

Why gHack?

The gHack “challenge” format is perfect for a team-based, hands-on learning experience.

gHacks are all about being “for the people, by the people”. Here are our core principles:

  • Anyone can contribute a gHack.
  • Anyone can use gHacks content to host their own event.
  • Anyone can modify the content as needed.
    • Submitting a pull request for modified/improved content is encouraged.
  • The content can be shared with attendees AFTER the event for continuity purposes.

What Does It Take To Create a gHack?

When you design a gHack, these are the steps you will run through:

If you create things in this order, you will be able to quickly flesh out a new hack.

Note The Coach’s guide is the most detail oriented & time consuming item to produce however, here’s a pro tip: Hack authors have been known to write the Coach’s Guide as a post-mortem from their first run of the hack.

Preparing Your Environment

Okay, ready to get started creating your own gHack?

First we create a fork of the main gHacks repo and then clone it to disk and create a branch to work in. The instructions below assume you have the git command line on your machine. If you’re more comfortable in a GUI git client, you can use that too (we recommend SourceTree).

  1. Create a fork of the gHacks repo
  2. Clone your new fork to your local machine
    • git clone https://github.com/myname/cloud-hackathons.git ./gHacks
    • cd gHacks
  3. Create a new branch for your work. It is a best practice to never work directly on the main branch
    • git checkout -b my-branch
  4. From the root folder, run
    • tools/setup-newhack.sh --hack=<name-of-your-hack> --author=<your email address> --title=<title of your hack>

      Note The title of your hack is the visible title, and should be human readable, it will be used to link to your hack from the front page (the catalog). Also make sure to use “snake-case” for your hack name, ie: use dashes between words

  5. A new folder will be created in the hacks folder with the name of your hack

Files and Folders

Now that you’ve run the setup-newhack.sh script above, this is the directory structure it creates and the template files within:

hacks
├── century-of-iot
│   ├── artifacts  # (Optional) Terraform setup 
│   │   ├── Makefile
│   │   ├── runtime.yaml
│   │   ├── main.tf
│   │   ├── providers.tf
│   │   ├── outputs.tf
│   │   └── variables.tf
│   ├── images  # (Optional) Images used for hack description and/or solutions 
│   │   ├── architecture.png
│   │   └── results.png
│   ├── resources # (Optional) Lecture presentations, supporting files, etc. Will be supplied to students
│   │   ├── Makefile
│   │   ├── lectures.pdf
│   │   ├── kube-deploy.yaml
│   │   └── testing.html
│   ├── README.md      # (Required) Hack description
│   ├── solutions.md   # (Required) The coach's guide
│   ├── QL_OWNER       # (Required for qwiklabs) Line separated list of owner & collaborator's emails for the Qwiklab
│   └── qwiklabs.yaml  # (Required for qwiklabs) Qwiklab configuration
└── ...

Student Guide

Why should someone take the time to deliver or participate in your hack? This is the main question you need to answer in order to define your hack. Every gHack needs to have a good executive summary that quickly describes your hack to those who will host or attend your hack. Think of this as your marketing pitch.

The Student Guide is the README.md that lives in the root of your hack’s top level folder.

The Student Guide must include the following:

Hack Title

Give your hack name. Keep it short, but consider giving it a “fun” name that is more than just the name of the technologies the hack will cover.

Introduction

This is your chance to sell the casual reader on why they should consider your hack. In a paragraph or two, consider answering the following questions:

  • What technologies or solutions will it cover?
  • Why are these technologies or solutions important or relevant to the industry?
  • What real world scenarios can these technologies or solutions be applied to?

Learning Objectives

This is where you describe the outcomes a hack attendee should have. Provide a short list of key learnings you expect someone to come away with when they complete this hack.

Challenges - Table of Contents

Every gHack is made up of a collection of technical challenges. Here we list out the challenges by name, with no more than a single sentence description for each unless the challenge title is descriptive enough on its own.

Because this is a table of contents, we recommend that you create links to the challenge text further down in the Student Guide.

Prerequisites

Provide a list of technical prerequisites for your hack here. List out assumed knowledge attendees should have to be successful with the hack. For example, if the hack is an “Introduction to Kubernetes”, the attendee should have a basic understanding of containers. However, if it is an “Advanced Kubernetes” hack, then the attendee should know the basics of Kubernetes and not ask you what a “pod” or “deployment” is.

Provide a list of tools/software that the attendee needs to install on their machine to complete the hack.

Contributors

Finally, give yourself and your fellow hack authors some credit. List the names and optionally contact info for all of the authors that have contributed to this hack.

Student Guide Template

To help you get started, we have provided a sample template for the Student Guide here:

Please copy this template into your hack’s root folder, rename it to README.md, and customize it for your hack.

Note It is a good idea to read through the example markdown in the template to familiarize yourself with the various sections. The sections marked as “(Optional)” do NOT need to be in your Student Guide if you don’t have content for those sections.

Challenge Design

Challenges are at the heart of the gHack format. Designing challenges is what a hack author should spend the majority of their time focusing on.

There are different approaches to designing a hackathon. If you are familiar with the Marvel Comic Universe movies, you know that they follow one of two patterns:

  • “Origin Story” - A movie focused on the back story of a SINGLE superhero that lets the audience get to know that character in depth (perhaps with a sidekick character or two included).
  • “Avengers Story” - A movie with an ensemble cast of superhero characters working together to solve a mega problem, with each character getting varying amounts of screen time.

You can use the same patterns when designing a gHack.

  • Singleton Hack - A hack designed to give in-depth hands-on experience with a specific technology and maybe a “sidekick technology” or two included.
  • Solution Hack - A hack designed to give experience solving a real-world scenario that involves using multiple technologies together for the solution.

Once you have decided what type of hack you want to create, you should follow these guidelines when designing the challenges:

  • Include a “Challenge 0” that helps attendees install all of the prerequisites that are required on their computer, virtual environment or GCP account.
  • Challenge descriptions should be shorter than this section on how to design challenges. Keep it to a couple of sentences or bullet points stating the goal(s) and perhaps a hint at the skill(s) needed.
  • Think through what skills/experience you want attendees to walk away with by completing each challenge
  • Challenges should be cumulative, building upon each other and they should:
    • Establish Confidence – Start small and simple (think “Hello World”)
    • Build Competence – By having successively more complex challenges.
  • Each challenge should provide educational value.
    • For example, if an attendee completes only 3 out of 7 challenges, they should still walk away feeling satisfied that they have learned something valuable.
  • Take into consideration that a challenge might have more than one way to solve it and that’s OK.
  • Provide verifiable success criteria for each challenge that lets the coaches and attendees know they have completed it.
  • Provide relevant links to learning resources that should lead the attendees toward the knowledge they need to complete the challenge.
  • Provide hints for items that could potentially be time consuming to figure out but are of low learning value or relevance to the actual goal of the challenge. EG: A command line parameter that is not obvious but would take hours to debug if it were missed.
  • Do NOT provide a list of step-by-step instructions. These are challenges designed to make the attendees learn by solving problems, not blindly following instructions.

Challenge Template

To help you get started, we have provided a sample markdown template for an individual gHack Challenge in the Student Guide Template.

If you haven’t already, please copy this template into your hack’s root folder and rename it to README.md.

For each of your challenges, you will add to the end of your Student Guide a new copy of the challenge template markdown that starts with:

## Challenge <#>: <Challenge Name>

Keep in mind that we’re using Github Flavored Markdown and support highlighting of blockquotes that start with > <span class="info"><svg class="octicon octicon-info" viewBox="0 0 16 16" version="1.1" width="16" height="16" aria-hidden="true"><path fill-rule="evenodd" d="M8 1.5a6.5 6.5 0 100 13 6.5 6.5 0 000-13zM0 8a8 8 0 1116 0A8 8 0 010 8zm6.5-.25A.75.75 0 017.25 7h1a.75.75 0 01.75.75v2.75h.25a.75.75 0 010 1.5h-2a.75.75 0 010-1.5h.25v-2h-.25a.75.75 0 01-.75-.75zM8 6a1 1 0 100-2 1 1 0 000 2z"></path></svg> Note</span> or > <span class="alert"><svg class="octicon octicon-alert" viewBox="0 0 16 16" version="1.1" width="16" height="16" aria-hidden="true"><path fill-rule="evenodd" d="M8.22 1.754a.25.25 0 00-.44 0L1.698 13.132a.25.25 0 00.22.368h12.164a.25.25 0 00.22-.368L8.22 1.754zm-1.763-.707c.659-1.234 2.427-1.234 3.086 0l6.082 11.378A1.75 1.75 0 0114.082 15H1.918a1.75 1.75 0 01-1.543-2.575L6.457 1.047zM9 11a1 1 0 11-2 0 1 1 0 012 0zm-.25-5.25a.75.75 0 00-1.5 0v2.5a.75.75 0 001.5 0v-2.5z"></path></svg> Warning</span>. In addition any line that ends with two spaces and a newline will cause renderer to emit a linebreak.

Student Resources Folder

It is common to provide attendees with resources in order to complete the hack’s challenges. One example is to provide the code for an application that the hack’s challenges are based on. Another example might be to provide sample or starter code files, artifacts, or templates that provide guidance for completing the hack’s challenges.

If your hack provides attendees with code or resources, they should be included with your hack’s contents in the resources folder.

During a gHack event, it is recommended that you have attendees download any provided resources as a zip file instead of having them clone the entire gHack repo onto their computer. Part of the How To Host a gHack guide gives instructions on how to make material available before your event.

This has the benefit of not having to direct the attendees to the gHack repo during your hack. Remember, attendees can always find the gHack repo. However, remind your attendees that they are cheating themselves out of an education if they go foraging around in the gHack repo for the answers.

Presentation Lectures

You may be wondering why there is a section called “Presentation Lectures” when the whole point of gHack is to be hands-on and not eyes front?

When you host a gHack event, there is always a kick off meeting where the attendees are welcomed and then introduced to the logistics of the hack. The best way to do that is with a short presentation delivered a few slides at a time.

After the kickoff meeting, its up to the hack authors if they want to provide any presentation lectures. Some hack challenges are easy to jump right into. Others are more complex and are better preceded by a brief introduction presentation.

It is OK and encouraged to offer a collection of “mini” presentation lectures if necessary for your hack’s challenges. If you do provide a presentation lecture, consider these guidelines for each challenge:

  • Try to limit the lectures to 5-10 minutes per challenge.
  • Provide a brief overview of the challenge scenario & success criteria
  • Provide a brief overview of concepts needed to complete the challenge
  • Provide “reference” slides that you might not present, but will have on hand if attendees need additional guidance
  • Provide a slide with the challenge description that can be displayed when attendees are working on that challenge

We have more guidance on how and when to deliver mini presentation lectures for your challenges during your event in the How To Host a gHack guide.

Please publish any presentations in your hack’s resources folder as a PDF file.

Coach’s Guide

Every gHack should come with a Coach’s guide. The simple way to think of the Coach’s guide is that should be the document with all of “the answers”. The reality is, doing so would turn it into a giant step-by-step document loaded with detailed commands, screenshots, and other resources that are certain to be obsolete the minute you publish it. No one wants to maintain a document like that.

Instead of treating the Coach’s guide like a step-by-step document, treat it as the “owner’s manual” you would want to provide to future coaches so they can host and deliver your gHack to others.

The Coach’s guide should include the following:

  • List of high-level solution steps to each challenge
  • List of known blockers (things attendees will get hung up on) and recommended hints for solving them. For example:
    • Resources that will take a long time to deploy in GCP: Go get a coffee.
    • Permission issues to be aware of, etc
  • List of key concepts that should be explained to/understood by attendees before a given challenge (perhaps with a presentation lecture)
  • List of reference links/articles/documentation that can be shared if attendees get stuck
  • Estimated time it would take an attendee to complete each challenge. This will help coaches track progress against expectation. It should NOT to be shared with attendees.
  • Suggested time a coach should wait before helping out if a team is not progressing past known blockers

The Coach’s guide should be updated during & post event with key learnings, such as all the gotchas, snags, and other unexpected blockers that your attendees hit.

Coach’s Guide Template

To help you get started, we have provided a sample markdown template for a Coach’s Guide in the Coach’s Guide Template.

Please copy this template into your hack’s top folder, rename it to solutions.md, customize it and add in all of your challenges.

Note It is a good idea to read through the example markdown in the template to familiarize yourself with the various sections. The sections marked as “(Optional)” do NOT need to be in your Coach’s Guide if you don’t have content for those sections.

Coach Solutions Folder

This is where you can put any completed scripts/templates/code files for the coach’s reference. It is understood that the solutions you provide here will be example solutions that represent ONE way to solve the challenges.

The solution resources might include a full working application, configuration files, populated templates, or other resources that can be used to demonstrate how to solve the challenges.

Examples of Coach solutions resources are:

  • Prerequisites for the GCP environment if needed.
    • Example: A VM image with Visual Studio or ML tools pre-installed.
    • Example: A Terraform template and/or script that builds out an environment that saves time on solving a challenge
  • Scripts/templates/etc for some challenges that can be shared with attendees if they get really stuck
    • Example: If challenges 1 through 3 build something (i.e. a GKE cluster) that is needed for challenge 4, you could “give” a stuck team the scripts so they could skip to challenge 4.

Note
This content is NOT intended for hack attendees to see before or during a hack event. The content IS available publicly and thus an attendee can and WILL find it if they are determined enough. It is important to stress to the attendees that they should not cheat themselves out of an education by looking at the solutions.