Teaching GitHub for Poets

by Aaron Suggs

The talk titled "Teaching GitHub for Poets" by Aaron Suggs at RailsConf 2015 highlights the initiative at Kickstarter to make coding contributions accessible to all employees, not just traditional developers. This effort is encapsulated in the program GitHub for Poets, a one-hour class aimed at providing all staff with the tools to modify the website using GitHub's workflow, enhancing organization-wide engagement in the engineering process.

Key Points Discussed:
- Introduction to GitHub for Poets: This class demystifies the GitHub flow, explaining how anyone in the organization can make changes without needing deep technical experience or access to complex tools. The goal is to encourage participation from all employees, transforming perceptions of coding from an obscure domain to a more inclusive activity.

Benefits of the Program:
- Accessibility: It allows any employee to engage with code changes, illustrating a lightweight process for correcting typos or improving copy, thus reducing the dependency on engineers for trivial updates.
- Cultural Shift: The initiative fosters transparency and inclusivity within the organization, enabling better communication and understanding of the engineering processes and their impact on everyone’s roles.
- Reduction in Support Bottlenecks: Community support teams can directly address user interface issues by proposing changes, which are more efficient than through traditional request channels.
Successful Implementation Examples:
- Staff members who participated have made substantial contributions, such as correcting confusing messages on the site without over-relying on the support teams. This not only reduces backlog but also empowers other departments.
- Noteworthy is the experience of Carol, who made 312 commits focusing on content clarity, demonstrating the effective involvement of non-technical staff in improving the site.
Security and Concerns: Suggs addresses common concerns about security and potential risks with broader access to code. He reassures that with the appropriate use of branches and a supportive culture, fears of breaking the site are manageable, underscoring Git as a communication tool.

Concluding Insights: The program illustrates that coding can be treated like writing, where proposals for changes are the seeds of collaboration. By fostering a culture where everyone feels empowered to contribute, organizations can benefit from enhanced creativity and collaboration, ultimately leading to a more dynamic and responsive workplace.

Furthermore, the success of GitHub for Poets at Kickstarter highlights the transformation from an elitist view of coding to a domain where every employee can directly participate, making a collective impact on the organization's projects.

00:00:12.160 All right, I think we can go ahead and get started. So you guys are in Teaching GitHub for Poets.

00:00:18.960 I am Aaron Suggs; I go by K Theory on social media. I'm the lead operations engineer at Kickstarter, and I'm a terrible dancer.

00:00:26.240 This is me dancing poorly in a grizzly bear suit, called the Grizz Coat; it was a Kickstarter reward.

00:00:38.719 I'm always a little nervous starting out these talks, but I feel like once you guys have seen me dancing poorly in a grizzly bear suit, there's nowhere to go but up.

00:00:50.800 I work at Kickstarter, whose mission is to help creative projects come to life. We are a Ruby on Rails application. You probably already know how it works: if you have an idea for a comic book, a film, a gadget, or a software project, you post your idea with a pitch video.

00:01:10.799 Your friends, family, and even strangers on the internet pledge money to it. That's sort of the ultimate way of saying, 'I want this thing to exist in the world.' If you get enough money to complete the project, we collect that money, pay it out to you, and you can go ahead and build the thing you wish to do.

00:01:22.240 In my role as operations engineer, it's my job and passion to create tools and processes that help the engineering team and the whole Kickstarter organization do awesome work. To that end, one of the programs we have is called GitHub for Poets.

00:01:38.640 So, a super quick outline of what I'm going to cover in this talk: I'm going to discuss what GitHub for Poets is, why it's awesome, useful, and beneficial for our organization—and for your organizations too—and how you can implement it yourself.

00:01:56.640 Jumping right into what GitHub for Poets is.

00:02:03.520 It's a really quick class; it takes about an hour and covers how to make a copy change to our website using the GitHub flow in a web browser. We go through finding a file we want to change, changing it, committing it, and making a pull request.

00:02:20.640 It's open to all staff; everybody in the organization is welcome to participate, not just developers, designers, or people you'd expect to be committing code and working directly with a Rails app.

00:02:38.879 It's also an introduction for everyone in the company to the tools and processes that the engineering team uses. We're really trying to make it accessible, clear, and transparent throughout the organization about what we’re working on.

00:02:45.519 The name GitHub for Poets, by the way, comes from a reference to a lot of liberal arts schools. My college, at least, had a class called Physics for Poets, aimed at people who wouldn’t become physics majors but want to enrich their lives by learning something about electromagnetism and relativity.

00:03:04.560 This is the idea that there are lots of people in our organizations who aren’t expected to be doing Rails development or working with GitHub on a day-to-day basis, but knowing something about it can really improve their workflow.

00:03:30.400 So, I wanted to dig in a little more into what each of these three bullet points entails. I’ll do a live demo of a copy change.

00:03:43.360 The GitHub flow and browser, for those who aren't familiar with it, is a way of just finding files, editing them, and committing those changes—all inside Chrome or Safari or something like that. The great thing about this process is there's nothing to download or install; you don’t have to tell people to open up a terminal or clone anything.

00:04:20.799 You're just searching in your GitHub repository just like you'd search Google. So the learning curve on getting started, both in terms of technical know-how and the commands you actually have to run, is very low.

00:04:38.720 This flow of finding a file to change, changing it, committing it, and making a pull request is the fundamental development loop. This is the cycle that all engineers, designers, and anyone building a product are doing over and over again. To show that and make it accessible for people who aren't familiar with it is a really powerful tool. This has significantly helped our community support team and integrity team.

00:05:03.680 They might be trying to find confusing parts on the site, like poorly written validations. They would use this to improve copy changes. Since we’re just changing text in views or emails, you don't really need to know Ruby programming at all.

00:05:28.320 We don’t need to get into how Ruby works or how Rails works much at all. This is the kind of thing you can cover in an hour and feel like you have a better understanding of how these processes work.

00:05:54.720 As I mentioned, it’s open to all staff. What that means at Kickstarter, which has about 110 employees, is that one-third of them work on the product, either as engineers, designers, or product managers. Most of the employees are engaged in HR, recruitment, or managing job postings.

00:06:16.240 They may also be involved in legal aspects, like upgrading our privacy policy or terms of use. These are code changes that are really just text changes, which people who have gone through our GitHub for Poets class can do.

00:06:27.520 A lot of the community support team can now make these kinds of changes in a much more straightforward way than before we implemented this class. It has grown to become part of the onboarding process for new employees. I think of it as analogous to how many companies have customer support rotations where every new employee spends a day answering support emails.

00:06:50.000 This experience provides a great way to understand what customers experience when they interact with the product. Similarly, if you want to know how the engineering and product development team works, introducing them to this code change cycle is really eye-opening.

00:07:07.680 Many people who aren’t familiar with it tend to assume that it involves complex genius hacker-type stuff, given its portrayal in Hollywood. However, when you show them that it really involves just changing some text in some files, it can greatly improve their understanding of how engineering works.

00:07:44.560 It's an introduction to the tools and processes. This also involves explaining how to run tests before deploying to production. We'll talk about how we have a continuous integration environment.

00:08:04.720 For example, when you sign up with a username and password and submit those details, you’re logged into the website, and we run tests to make sure multiple users can’t sign up with the same email address.

00:08:21.360 We explain just enough about GitHub so you really need to do that development loop, which is fundamentally about commits and branches.

00:08:30.560 If you understand a commit as a single change with a message describing why you did that change to a file, that’s what a commit is; a branch is just a representation of all those changes being made throughout history. Any branch can represent the work you’ve been doing; these branches are safe places for you to do your work without impacting anyone else's work.

00:09:00.080 Rails, as we explain, is a collection of tools for building dynamic websites. You don’t have to go into the nitty-gritty of how Active Record works; you just need to show the directory layout where most of the copy lives in app views or app mailers views, or maybe in configuration and YAML files.

00:09:11.600 This approach has made the engineering process transparent and inclusive for everyone in the Kickstarter organization. Because people—poets—are going through this process and doing this loop, we find ourselves in a place where everyone in our organization can commit code.

00:09:35.360 Many people, when they hear this, initially react with apprehension.

00:09:50.040 I'm the guy in the middle who thinks it’s pretty great. So, what happens when you let everyone in your organization commit code? It actually works out pretty well, and I’m going to delve into the reasons why GitHub for Poets is awesome.

00:10:05.920 The biggest reason is it makes our process more lightweight for getting information and making easy changes. In the past, our community support team would notice that a validation message was confusing and generating a lot of support tickets.

00:10:23.600 Or they might spot typos on the site, leading people to write in requesting corrections. Since most of the copy was written by engineers, they would tell this to their VP of community support.

00:10:43.120 That VP would subsequently have a weekly meeting with the VP of engineering to discuss these changes. They would then file simple changes into our ticketing system for an engineer to fix the typo or clarify the message, which is just excessive.

00:11:07.279 Now, with GitHub for Poets, the person who notices a typo or a confusing validation can edit the file themselves, submit a pull request, and an engineer will get a notification to merge and deploy it shortly thereafter.

00:11:32.959 This keeps everyone else informed without placing them in that critical path. They can see what happened and no longer have to wait for their boss's permission to make changes.

00:11:46.320 Another fantastic reason for GitHub for Poets is that it helps you avoid building a Content Management System (CMS). As you're creating minimum viable product features and experimenting, there can be a phase of a product where it might need to become a CMS.

00:12:12.720 Having GitHub for Poets lets us say to people, 'You can just go in and edit this view.' Since we use HAML, which is really easy to learn, you can copy chunks around, and if the tests pass, it means there’s no syntax error.

00:12:39.360 We check it on staging before it goes to production, making it a low-risk change that saves engineering effort by not having to store all this content in a database when we don't know what the feature's full life cycle will be.

00:13:06.560 Another way to look at it is that version control acts as a content management system, and we're allowing everyone to use that instead of building a bespoke CMS.

00:13:31.120 These are very practical reasons for implementing GitHub for Poets; it saves work and increases the productivity of the engineering team. However, the real awesome benefits, I think, come from the cultural values and reasons for doing this.

00:13:55.760 Initially, GitHub for Poets was going to be Ruby on Rails for Poets, as we wanted to teach some people Ruby and Rails. We have a Ruby on Rails application, and we thought, 'We'll just show you how it works.'

00:14:20.800 However, it turned out to be too ambitious to cover all of this material in a couple of hours. In fact, boot camps last 12 weeks, and we’ve now discovered it was better to focus on how Git works.

00:14:38.560 The mind-blowing aspect is that you provide so much transparency and context about every change that anyone has made. We ended up discussing how GitHub works for the entire time.

00:14:57.760 So, our values here, which we’re realizing, is that we wanted to improve transparency in our engineering process. Sometimes, features are approaching release, and at the last minute, we discover a security vulnerability or a performance issue.

00:15:24.000 It’s invaluable for the marketing team to understand why there's a delay, particularly when we’re incorporating extra features.

00:15:37.520 That's part of the workflow that improves transparency and inclusivity. There's also widespread consensus that involves the pull request cycle, which was surprisingly different from how many other departments make decisions.

00:15:51.280 What we're realizing is that version control is a vital communication tool, similar to chat platforms or email clients. Everyone in your organization should have access to your chatroom, and everyone should have an email address to communicate.

00:16:05.440 Your version control—GitHub or otherwise—is this rich history of why you've built things the way you have. It’s incredibly useful for understanding that the product was built with context and solid reasoning from pull requests.

00:16:21.600 Moreover, you discover that some changes you view as simple aren’t actually that straightforward.

00:16:37.040 It’s really amazing to realize that as we work, we’re building this narrative of how we created things through our Git commit history. I think of this as a fish in water moment, where, like the fish unaware of the water they're swimming in, engineers become accustomed to how version control provides invaluable context.

00:17:03.200 As other teams observe this, they, too, want that transparency in their projects. They start creating their own repositories for documentation or policy documents on how they handle various situations.

00:17:29.440 These decisions now come with a complete commit history, a pull request, and a rich context around the discussions about how and why things were performed a certain way.

00:17:47.760 While this is called GitHub for Poets, it is also applicable to any version control system. The distinctive piece I appreciate about GitHub's pull requests is that you can achieve consensus.

00:18:01.760 Those discussions occurring around pull requests provide richer context. For instance, there may be a product manager urging for a speedy rollout to meet a deadline or a security engineer addressing security trade-offs.

00:18:17.840 When everyone in the organization engages on GitHub, it would even include marketing personnel who can offer timely modifications to marketing copy for a new feature.

00:18:35.040 There's an inherent shared responsibility in pull requests. If something malfunctioned due to merging one’s pull request, it isn’t fully on you, especially since we maintain a supportive culture.

00:19:00.000 It’s not the sole accountability of the individual but an expectation to inquire how improvements can be made. This expectation fosters a more mature environment for teams to collaborate.

00:19:19.840 As other departments see how engineering approaches this, they want to adopt that culture themselves.

00:19:32.000 This is my personal reason for supporting GitHub for Poets: it's an effective way to increase your impact within the organization. As you progress in your career, one of your boss’s expectations is to have a greater impact.

00:19:55.680 You should be able to manage your workload effectively, improve your team’s workflow, and, ultimately, enhance processes across the organization.

00:20:16.320 GitHub for Poets involves only a few hours of your time teaching and assisting your coworkers with their GitHub organization.

00:20:33.039 Answering their questions as they arise and merging and deploying their pull requests when they're ready can result in a substantial alteration to their workflows.

00:20:51.440 This approach equips them with better tools—a toolkit they can employ—which fosters a more positive attitude around requesting consensus and expecting transparency.

00:21:06.080 Ultimately, the final reason to consider GitHub for Poets is that your boss will appreciate it, and you will contribute positively to your organization.

00:21:22.720 Now, how to implement GitHub for Poets? This is somewhat of a whirlwind tour, or even a mini session on what GitHub for Poets looks like at Kickstarter.

00:21:39.840 The initial topics I explain are how branches and commits work, which is essential knowledge for using GitHub.com effectively.

00:21:54.080 We cover the standard Rails file layout, emphasizing key locations like app views, app mailer views, and the configuration file, particularly if there are many YAML files with copy.

00:22:11.600 A helpful analogy, as shared by my friend Emily Reese, who co-taught the class with me, is that when in college, each semester would yield a folder containing all your classes and term papers—all interlinked.

00:22:33.679 This hierarchical structure of folders is akin to how our code bases ultimately work, helping those unfamiliar with programming understand the layout.

00:22:46.560 An essential aspect is the idea of always being in a state of learning. Many hesitate to contribute because they feel they must become experts before making a change.

00:23:06.880 It's crucial to dissuade them of the belief that they’ll feel like experts because, in reality, engineers don’t feel like experts either.

00:23:29.440 This ‘always be learning’ concept warrants its slide within the presentation.

00:23:42.640 One of the most helpful things during these GitHub for Poets classes is demystifying the development process. Our engineering team has sometimes been glorified as elite, smart hackers with some sort of communal intelligence with computers.

00:23:57.600 But in reality, we are just trying to perform simple tasks. We generate Rails scaffolding and search for gems that accomplish our goals without the need for cleverness.

00:24:13.760 So it's important to reduce the barriers to entry and the knowledge necessary to get started.

00:24:25.760 I like to discuss how this aligns with the philosophy of DRY—Don't Repeat Yourself—on a macro level, which means if you’re writing code to accomplish something you've done before, it’s inefficient.

00:24:43.919 Instead, you should be reusing the code you've already written.

00:24:58.000 So, you should feel comfortable working at the edge of your comfort level, and it’s perfectly acceptable to seek assistance from an engineer when unsure about a file or Git history.

00:25:23.440 Engineers frequently ask for help from Google or Stack Overflow.

00:25:37.040 This wraps up the core of what I cover in a GitHub for Poets session. I also wanted to offer a live demonstration of what it entails.

00:25:51.600 If anyone wants to follow along, I'm going to GitHub.com/k_theory/rails_demo and we’ll see how well my networking works.

00:26:09.920 Let me adjust to mirror displays.

00:26:32.000 Here we go!

00:26:47.520 We’re looking at a very standard Rails application, where I just created a user model scaffold. The whimsical copy edit we’re about to make will enhance the SEO of the user listing.

00:27:08.160 To find it, I'm going to search the application for the user listing, and I’ll show you how to access the app views, specifically, app/views/users/index.html.erb.

00:27:21.440 Next, I’m clicking on one of these lines I intend to edit. This looks like HTML, and there’s a bit of magic I won’t concern myself with right now.

00:27:39.520 Before I proceed with the editing, I need to switch from the particular tree back to a branch. I’ll be editing this file to express my appreciation of monoliths.

00:27:56.960 Let's add a subheader to assert: 'Monoliths are...' Now, it’s your turn to participate: what do you think monoliths are?

00:28:14.320 (Audience participation) Majestic integrated systems!

00:28:49.760 Now I’ll commit these changes to a new branch. I’m updating the user listing to add SEO around monoliths, and yes, emojis are always a nice touch!

00:29:06.080 After proposing the file change, we can specify the feedback we’d like to get on the pull request.

00:29:22.960 It could say, 'Please check if monoliths are actually majestic and integrated!' Let’s also mention someone known in the community for feedback.

00:29:39.680 Now, we can create our pull request. In our process, the next step entails a support engineer checking if everything looks good; this is on a weekly rotating basis.

00:29:51.840 If our continuous integration is set up properly, we'll receive a nice green checkmark indicating all is well. Once it checks out fine, the engineer will deploy the changes.

00:30:06.080 Thanks! It's great to see participation in this pull request.

00:30:23.280 Now, returning to the slides—there are common concerns people might have when considering audience access to their GitHub repository.

00:30:38.560 The most common worry I hear is that users might break the site. I’d argue that the poets tend to be even more cautious about this than the engineers.

00:30:53.040 As a result, those who’ve gone through the GitHub for Poets process tend to approach their modifications cautiously, often seeking assistance even when they’re making only trivial changes like fixing typos.

00:31:09.520 The worst outcome we’ve encountered has just been related to HAML; perhaps indentation issues emerged and we discover this when tests fail.

00:31:25.840 So yeah, these are really low-risk changes, yet they can significantly increase usability on your site.

00:31:39.920 We’ve not found that giving more people access to our code repository has decreased code quality or become a liability to the website; if anything, it has had the opposite effect.

00:31:54.320 Another concern relates to security. Many might think that our code is so special that its accessibility is risky.

00:32:09.280 But I think that's an unfounded fear. Version control serves as a communication tool similar to chat; there's always a chance unintentionally leaked information could create controversy.

00:32:26.240 Although that is a risk, it's often outweighed by the tremendous productivity gains provided by tools like chat and email.

00:32:41.920 There are straightforward techniques you can implement to bolster security. For instance, requiring all employees to use one password to ensure strong and unique passwords across websites.

00:33:02.640 You can also enforce two-factor authentication for critical accounts. And remember, your code is not a trade secret; it's generally mundane Rails applications with a few customizations.

00:33:14.480 If someone were to leak our code, we’d like to think an experienced Rails engineer would find it straightforward, even more so if it’s obscured by clever app ingenuity.

00:33:31.440 To ensure security and maintain the integrity of the site, reminders can be useful.

00:33:46.560 First, poets should recognize they are working in their own Git branch—a safe space to experiment without affecting others.

00:34:02.720 Second, we have continuous integration and thorough testing processes to catch issues before deployment.

00:34:20.640 Our deploy process requires whoever's deploying to verify which commits are being included and ensure they align with expectations.

00:34:32.880 In the event a poet forgets to create a branch and commits directly onto master, this can trigger a conversation in our chat room, allowing the team to evaluate whether it’s important.

00:34:48.640 If it's not a priority, we might consider reverting and pursuing the pull request workflow instead.

00:35:03.520 Another frequent inquiry relates to the meaning behind receiving a thumbs up on a pull request, as it can carry multiple connotations.

00:35:19.600 Does it indicate approval for the merge and deployment? Or do they merely appreciate the idea being presented without endorsing the specific implementation?

00:35:32.160 This is a surprisingly nuanced emoji to navigate.

00:35:52.800 Now, I want to highlight some of the poets at Kickstarter who have successfully navigated through the GitHub for Poets program.

00:36:05.600 These are employees who have participated in the class and gone on to make multiple commits and pull requests.

00:36:15.680 Of the 70 or so individuals who went through the program, 29 of them have ultimately made pull requests that were merged into master, resulting in a total of 1,100 commits.

00:36:35.440 I find that truly amazing; that equates to 1,100 instances where a developer didn't get interrupted to make a trivial copy change. It saves time and positively impacts people's workflows.

00:36:53.760 There’s a remarkable anecdote about this: a puzzling part of our video uploader caused significant confusion among creators reporting they couldn't see a preview. Instead of writing a response to thousands of tickets, one staff member just edited the HTML.

00:37:09.120 They added helpful text indicating the preview would be displayed on the next page—a straightforward fix that greatly reduced support tickets.

00:37:23.920 In the long run, we also wanted to implement improvements where users could more seamlessly view previews, but this immediate update was a considerable achievement.

00:37:35.440 Lastly, I want to acknowledge Carol, who has alone made 312 of those commits. She’s now part of our copywriting team, greatly enhancing the impact of our content.

00:37:56.560 Early in her time here, she combed through the site searching for instances where we failed to use serial commas. She was diligent in ensuring clarity.

00:38:09.760 Her early contributions included countless pull requests, each centered around correcting the use of serial commas, reinforcing the standards expected of our written communication.

00:38:23.840 We conclude with Emma, a colleague, who made a pull request showcasing creativity. She received feedback from other engineers shortly after submitting it.

00:38:43.760 Getting recognition for contributions, especially on one's first pull request, is a huge milestone.

00:38:59.280 In closing, I hope to foster a cultural shift where coding feels more like writing. Written language is a comprehensive tool for expressing thoughts and ideas, requiring significant investment to learn.

00:39:10.640 I envision a future where using software and computers holds similar importance, where GitHub for Poets can make the development process accessible.

00:39:22.800 This enables people to tackle problems by editing our code base rather than feeling alienated from engineering.

00:39:34.720 The final slides include examples from the Kickstarter homepage that poets have contributed, showcasing their creativity in our GitHub for Poets class.

00:39:54.560 Here’s a screenshot of the homepage at one point featuring a large graphic highlighting films. Our poets came up with some whimsical edits!

00:40:09.920 Additionally, when discussing video games, Catherine transformed a standard backer number into a fun dogecoin meme with the call to action to send more dogecoins!

00:40:22.640 The last example highlights library projects but also demonstrates how GitHub for Poets often ends up resulting in a delightful chaos.

00:40:37.920 That concludes my talk. I'm K Theory on social media; feel free to reach out. I have time for some questions if anyone's interested.

00:40:54.080 And just in case there are folks here really wanting some poetry, I’ll leave you with some bad git poetry. Thank you!

00:41:40.240 (Audience applause)