All Basecamp policies are now on GitHub and licensed under creative commons

“Until The End of The Internet” is just one of the many policies we’ve decided to share

We try hard to write good policies at Basecamp. Make them plain and easy to understand. Without out all the dreaded legalese. By humans, for humans.

I particularly like our refund policy and our Until The End of The Internet policy.

But I’m sure we don’t always succeed. And sometimes our policies may decay over time. Terms that are or become unreasonable linger on. Ugh.

So that’s why we now invite our customers and anyone else who’s interested in reviewing our policies to collaborate on making them better, making them fairer. To this purpose, we’ve put all our Basecamp policies on GitHub!

This also means that every revision is tracked and date stamped. You can even subscribe to be updated whenever they change, if you care to follow along at that level.

Furthermore, since the spirit of this idea is to collaborate, we’ve also licensed all these policies under the Creative Commons Attribution license. If you’d like to use any of the policies for your own business, feel free! All we ask is that you give us a bit of credit, if you either copy them entirely or materially.

This act of sharing was inspired by the reception to opening up our Basecamp Employee Handbook. We’ve heard from so many business owners and employees that our handbook helped them put together their own. That they were inspired by some of our values or practices enough to adopt them as their own.

Our hope is that the same might happen with our policies. If more companies would adopt a no-nonsense refund policy, we’d all be better off. If more companies — AND YES I’M LOOKING AT YOU GOOGLE 😂 — would honor their legacy systems, and not willy-nilly kick users to the curb, we’d all gain from the level-up in trust.

Policies are part of the organizational code of a company. Not only should that code be open source, it should be tinkered with, improved, critiqued, forked, and refactored. Let’s do that.

The future of the Android community is YOU

If you’ve been paying attention to what’s been going on in our community — conferences, meetups, blog posts, podcasts, open source (the list goes on and on) — you’ve probably noticed a really wonderful energy and spirit behind them all. Yes, our community is healthy and thriving!

And while things are really good today, I do think that we all have a responsibility to think about the future of our community — to really consider what we’re going to do to help shape what it will become, not just for ourselves, but for all the new folks that will be coming into Android for many years to come.

But before we get into the future, let’s take a step back and consider why our community even means so much to us. Why do we even care? The best place I can think to start is my own story.

🤤 My (boring) story

I started with Android back in 2014, which wasn’t really that long ago. I had been writing Java for a long time before that, but didn’t know anything about Android. So I had a bunch of stuff to learn — all the APIs, UI frameworks, etc. were all new to me.

Like many people, a natural place for me to learn was at work, on the job. And that’s exactly what I did. I learned a lot from my coworker Jay. Jay really taught me the ropes and helped me get off on the right foot. He put up the guardrails so I wouldn’t go careening off the side of a cliff.

Turns out though that Jay has a life, a family, and his own work to do. He couldn’t be my personal Stack Overflow, 24/7. So yes, of course, there are limits to what our coworkers can provide. They’re a wonderful people that help us in our projects and day to day work, but naturally they have a bunch of their own stuff to do!

And so like just like everyone else, I started Googling around for resources that would help me become a better Android developer. But what I found wasn’t just a bunch of “resources”. Instead I found an incredibly rich network of teachers.

My peers were out there teaching and offering help without asking for anything in return. They covered every kind of topic and every kind of app. It was really amazing to see, and these teachers became a big, big part of how I learned and got a lot better at Android.

In fact, I’m certain that I don’t reach this level in my career without them. That is why this community means so much to me — I’m literally not here today without the help of all of you out there. So thank you!

I bet a lot of you feel the same way and maybe have similar stories. If you stop for a second and think about it, we’ve all been impacted by these amazing contributions in some way. Think of the conference video that got you really jazzed about something for the first time. Or the blog post that finally, for the first time, helped a concept click in your brain. And of course there’s all the open source work that all of our apps are built on.

And so if you think about how much benefit we’ve gotten from this community and what a positive influence its been on us, here’s a scary thought…

🙀 Can you imagine if this community didn’t exist?

What would happen? Well, for sure our jobs would be a lot harder, they’d be a lot less fun, and a lot less interesting. We’d find ourselves solving the same problems over and over, and it’d get tiring and tedious real fast. I wonder how many of us would even be making Android apps still.

Now of course our community isn’t going to magically disappear or anything like that. But I do think it’s healthy to occasionally reflect on stuff like this — to make sure we don’t take things for granted, and to help us appreciate what we have.

And this thought, as scary as it is, does highlight one really important aspect about communities that people probably don’t think about too often: that sustaining a healthy community is really hard work.

Sustaining any community is tough, and it’s especially difficult to sustain one at a high level like our’s is at. Communities don’t build themselves, they’re not some miracle of the universe. They’re the result of hard work of thousands of well-meaning people, donating their time and effort to help all of us.

I think this can be easy to forget sometimes because there are some folks within our community who are super-pros at doing this stuff. They make it look so easy, you could be forgiven to think that it’s no big deal for them to create these contributions.

But in reality it’s hundreds and hundreds of hours of effort to build these things. Whether it’s maintaining an open source project, prepping a talk, putting on a conference, or the dozens of other types of contributions, these things take a lot of time to put together. And often people are doing this on their own personal time. I don’t say this to make you feel bad for these folks or make it seem like they’re martyrs or something — it’s just to level set how much work really goes into this stuff.

The other thing that makes sustaining a community tough is that Android moves really fast. If you look back 2–3 years almost nothing is the same. Hell, if you look back a few months at Google I/O, almost nothing is the same! This is awesome and exciting of course, but it also means it’s really hard to keep up and cover it all. There’s a wide surface area of topics, and a relatively small number of contributors.

And so because it’s so much work, and because things move so fast, what you often see is that there are natural ebbs and flows to contributions. It’s not uncommon to hear about people taking a break from giving talks, or perhaps you’ve seen an open-source project go unmaintained. Life happens, work picks up, or any number of other factors can play a part, and this is absolutely natural and OK. Of course people deserve a break and should only contribute when it works for them.

But because people are cycling out, we need to make sure that we’re also cycling people in. And so if we truly appreciate this community, and you’ve positively benefited in any way from its contributions…

👉😳 We need you to become contributors

This is especially true for folks who haven’t been super active before. It’s really important to remember that new voices are a key element in moving us in the right direction.

New folks bring many important qualities to the table, but there are two that I really want to highlight.

Your energy. When starting something new, people have a natural energy about them. You’re excited and energized by the possibilities, and that’s important. That energy has a halo effect, not only around those you’re with every day, but also to other members of the community — that energy is contagious! When we see someone doing something new and exciting and full of enthusiasm, that keeps us motivated, interested, and energized too.

Your diverse perspectives. We don’t want to become a stagnant community of unchangeable ideas. New people naturally bring in fresh ideas, new angles, new ways of thinking, tend to challenge the status quo, and bring up issues that we might be blind to.

These two qualities are really, really important for us to have within our community. But unfortunately, a lot of times when encouraging new folks to get involved, there are a couple common retorts that I’ll hear.

“I have nothing new to say.” There’s this common misconception that people have. This idea that “I have nothing to contribute” or “Everything I would talk about has already been said by someone else.”

And while I understand where you’re coming from, I’m sorry to say you’re 100% wrong. You do have something to say whether you realize it or not.

Here’s the thing: the sum total of your life experiences, everything that’s gotten you to where you are today — your journey, your struggles, your successes — are incredibly unique and valuable. And because of that, someone out there can learn from you.

Even if by some chance you and I had the exact same skill level and were giving talks on the exact same topic, there’s no way that it would impact the same people the same way. Your unique vision of the topic, how you express it, and your perspective that’s been built up all your life carries an inherent value that nobody else can recreate. End of story.

“I’m just a beginner.” This is the other thing I’ll hear a lot — this idea that “I’m just starting out and I’m not an expert”. But what you may not realize is that, in some ways, being a beginner is a huge advantage that you have. How can that be?

There’s this wonderful quote by Kim Scott, the author of Radical Candor. In it she says…

“The essence of making an idea clear requires a deep understanding not only of the idea but also of the person to whom one is explaining the idea.”

That makes a lot of sense, right? Now I could expound on this, but why do that when my esteemed colleague Christina Lee has already done that so eloquently.

Exactly! You were just in the person’s shoe’s, of course you’re in an excellent position to explain it to another beginner more clearly than an “expert”. Some of us are so far removed from being a beginner that sometimes we’re not good at teaching — we can glaze over important steps, make a lot of assumptions, and even use different language. But as a beginner, you are immune to all of that, and that in many ways makes you a perfect teacher.

All that to say, you have to get those negative thoughts out of your head. Forget this idea that you have nothing to say, that you’re “just” a beginner, or whatever other doubts you might have. I guarantee you every contributor has said this or something similar before they got started.

The thing that’s hard to see until you jump in is that this is one of the most open, accessible, and encouraging groups of people you could be a part of. Everybody is, in my experience, incredibly nice and willing to help other get started.

A quick story — a little while back I was thinking of doing my first talk. I had never even submitted a proposal much less give a talk, so I had no idea what I was doing. I saw that Android Summit was coming up, and it looked like a good place for me to get started and so I was interested in submitting a proposal.

But like I said, I hadn’t the slightest idea what i was doing. So I looked up who had previously spoken there, and I saw that Huyen Tue Dao had given a talk the previous year. Now at this point, you have to remember, Huyen and I aren’t friends. Hell, we had never even talked to each other before. But out of the blue I sent her a message and asked for her opinion.

It was incredible! She gave me so much encouragement and advice, I could barely believe it. I went in the conversation cold and anxious, and came out excited and enthusiastic. And remember, we didn’t even know each other at all! Here’s a tiny excerpt of what Huyen told me from that conversation:

“Yes, you should totally propose a talk. Do it. End of story. If you have any questions let me know. You gotta go for it. Would love to help. You’ll do great! Let me know!”

That is an amazingly warm, open, encouraging way to treat someone you don’t know! To that end, I think it’s a wonderful embodiment of what our community is like.

The other thing that’s tough to realize until you get going is what an immensely rewarding experience being a contributor can be. If you think about it, there aren’t many professional endeavors where you can…

  • Help others, teach, and pay forward all the things you’ve gained
  • Make new friends and contacts all across the world at many companies
  • Improve your own skills and your career prospects, at the same time

If nothing else, those are three pretty damn good reasons, don’t you think?

🙌 So you’re convinced, right?

I hope at this point you’re convinced that our community is immensely important and valuable, that you absolutely have an important voice, and that we need as many people as possible to contribute to keep things going in the right direction.

So your next logical question might be, “OK, what do I do now? How do I start?”

Well lucky for you I’ve thought of four ways you can contribute. Each one is a little bit different, and I picked them because I think they might appeal to a range of different personality types. I hope there’s a little bit for everyone here. I’ll go into each one broadly and give you a few tips on how to get started. (These four are, of course, not the only things you could be doing, just the ones I happened to pick.)

Let’s get started!

✍️ Contribution #1: Writing

Writing is really near and dear to me, and it’s one of the most important skills you can have. I think many of us have probably read a blog post at some point that had a big impact on us or helped something really click for the first time. And given that so much of our work is writing — chatting, pull requests, feature descriptions, etc. — you could argue that it’s a vastly under-appreciated skill.

Specifically, there are a few things that make them immensely useful to our community.

It’s information dense. The written form is capable of carrying an awesome amount of information — they’re often packed with diagrams, explanations, and code snippets. Pound for pound, nothing can really match a written post for learning, especially compared to something like video or audio.

It’s self-paced. People can absorb the information at their own pace, which is really, really important for learning. I don’t know about all of you, but I usually have to read things at least twice to make any sense of something, sometimes more. Others can probably blow through stuff very quickly the first time. But that’s why it’s great — no two people learn at the same pace, and writing is by far the easiest way to guide your own pace (again, compared to something like audio or video).

It’s an excellent reference (basically forever). Once you’ve created something, you’ll find that it serves as an excellent reference on that topic for many years to come, especially if it’s on a topic that doesn’t change that often.

There’s this great tweet by Kelly Shuster regarding an article that Amanda Hill wrote a while back on image scaling types, and she’s absolutely right. Being able to go back to that article, time and time again, is a huge win.

Our friend Chiu-Ki Chan has expressed a similar sentiment, saying how she often writes to serve as a reference to herself, which is tremendously helpful too.

So if writing sounds like something you might be into, a few things to keep in mind.

Writing tip #1: Practice editing (a lot) ✂️

When you first start writing, one of the hardest things to do is to write clearly. And one of the best ways to improve clarity is to edit.

I read so many things every day that could benefit by a good round of editing — an email, a blog post, a news article, and so much more. Now this isn’t a criticism of those writers, far from it. I think it’s just a reflection of how hard it is to consistently write clearly. Hell, I struggle with it plenty, too. It’s a learned skill and it takes a while to get good at it.

Editing is a big topic so I don’t want to get too deep into the nuts and bolts of it, but there are three “types” of editing that I think would serve you well when writing for the community.

Cut the fat. I think this is probably the one that most people think of as editing, and rightfully so. Condensing everything to the bare minimum, using as few words as possible, and still clearly expressing an idea is incredibly important.

But there are two other kinds of editing that I think people sometimes forget about.

Revise and reorganize. A lot of times a good round of editing isn’t just about cutting things out. At some point there’s going to be a diminishing return for paring down your words too much. Sometimes editing is just about moving stuff around — moving a paragraph, sentence, or even just a single a word— to improve its clarity. Don’t forget that!

Use simpler words. One of the easiest traps to fall into is using complex language. I do this all the time too, I think because it makes me feel really smart or witty. But the reality is that if you have a choice between a simple word or a complicated/fancy one, always pick the simpler one. It will almost always serve you better, be easier to understand, and therefore will be more valuable to the reader.

Bottom line: editing is absolutely crucial to writing well. Practice early and often!

Writing tip #2: Claps are not a measure of success, impact, or value 👏🚮

It seems like every site these days has some way of providing “positive” feedback. Twitter has hearts, Medium has claps, and on and on.

And sure, I’m not going to lie to you, it feels good to get a lot of those. If you write on Medium and you get a ton of claps, it feels like you did something great and important — like you really struck a chord with people.

But if we’re being honest with each other, they’re all bullshit metrics.

From my own personal experience, some of the best things I’ve written that I was most proud of got very few claps or attention. And some of the most outrageous, antagonizing shit that I wrote got an absolute ton of claps. Does that make the latter more successful or more valuable?

Of course not. You absolutely cannot measure the impact that your writing can have by some arbitrary metric like claps, which are designed for Medium to get readers and clicks, not to serve your writing.

I really want to drive this home because sometimes new writers will think “Well, nobody clapped for my writing, so I’m not helping anyone. There’s no point in continuing.” And while I understand why you might feel that way, I urge you to persevere.

It’s possible that your work will live on for years and years, and eventually find its way to helping someone. Plus, how do you really know that it hasn’t helped someone? As unfortunate as it is, we often don’t read something useful then go through the trouble of contacting the author and tell them how much we appreciate it. For all you know, your article has made a tremendous impact on someone, they just didn’t go through the trouble of going back and saying thanks.

And worst case, remember you’re not just helping others, you’re helping yourself! I guarantee you that while you were writing the post, you learned something useful. And on top of that, you’ve got a wonderful bit of writing for your portfolio.

Don’t get too hung up on these bullshit metrics. You’re creating something useful, giving back to our community, and building up your skills and portfolio at the same time. Forget the claps and focus on the writing.

Writing tip #3: Have a strong opinion 💪

Don’t be afraid to tell it how you see it. We talked earlier about how writing clearly is one of the hardest things to do, and this is another way to really improve that.

Having a strong opinion means you are inherently being clear. When you’re being direct, that’s clarity. When you’re being wishy washy or qualifying every statement with “You may not all agree, but I think…” then your writing and clarity suffer badly.

Now of course that doesn’t mean you’re not responsible for what you say — far from it. You are absolutely responsible for being respectful, accurate, and convincing. But while doing that, be confident, be convincing, and say what you mean.

And hey, if everyone doesn’t agree with you (which they certainly won’t), don’t fret. Discourse, discussion, and disagreement is a normal, healthy thing in a active community. If you’ve riled up a few people and got ’em thinking, you’ve done good.

🗣 Contribution #2: Speaking

If writing isn’t your thing, maybe you’d rather just say it from a stage?

Speaking definitely isn’t for everyone — it’s insanely nerve-racking and an absolute ton of work. We’ve all heard the statistic of how people fear public speaking over death, right? Sounds like a blast!

The good(?) news is that this doesn’t just affect new speakers. Even the most experienced speakers run into this. Hadi Hariri, Kotlin guru and developer advocate at Jetbrains, aptly said:

Pretty damn accurate! So given how terrifying and hard it is to do, why would anyone want to do this? Well, there’s one amazingly thing that speaking can do better that no other medium can do…

Speaking is the single best way to inspire and motivate.

If I think back on the things I’ve often been motivated or inspired by, they’ve been talks. Whether they were conference talks about technical topics or a a Ted talk about life, these speeches have always had the greatest impact on me. Writing and reading are awesome, but they simply don’t convey the same kind of energy and excitement as someone speaking on stage. This is why people go see live events!

Another reason you might be interested? Well, speaking is “fun”, in sort of a sadistic, strange away. There is an amazing burst of excitement and energy that you get as your talk gets close, and nothing gets your ass in gear faster than a speaking deadline. And when it’s all done and you walk off that stage, it feels really rewarding when you pull it off.

And lastly, speaking has the potential to open up new opportunities for you. Donn Felker has this great article that he wrote a while back about the first time he publicly spoke. He talks about how he blacked out and all the nerves, but the most important thing he said was this:

“That one day led to many job offers…to do bigger and better things…I decided to jump and go work for myself as a consultant. How? All from speaking.”

For me the opportunities weren’t so much professional as they were personal — the connections and friendships that I’ve made from speaking are the most important “opportunities” that I was able to unlock. I’ve met some truly incredible people and developed friendships that I would’ve never otherwise.

So, if that sounds like your cup of tea, what are some things to keep in mind?

Speaking tip #1: There’s no right or wrong way to start 👆👇👈👉😕

When you first start thinking about speaking, you’re going to have a lot of questions. Where do I do my first talk — brown bag, meetups, conference? How should I prepare? What topic should I discuss? How do you write a CFP?!

And while of course those answers do matter, the key isn’t to get those answers — the key is to START.

Start down the path you think is right. What you want to avoid is becoming completely paralyzed from being unsure and trying to do everything “right”. Try to start answering those questions yourself, and see what you come up with.

After you’ve gotten going, start soliciting for help. Ask people for their opinions and work them into what you’re doing. But at the same time, don’t take any advice as gospel. It’s important to remember that ultimately it’s going to come down to knowing yourself and doing what you’re most comfortable with.

As an example, I’m really weird. The first talk I ever did was at a conference. I prepare by writing my slides and practicing by myself — literally nobody ever sees my talk before I do it. I pick a topic I’m interested, and I write the CFP myself without any feedback.

That works for me. If you couldn’t tell, I’m fiercely independent and slightly neurotic, so I tend to do a lot of stuff myself. So far it’s worked out fine for me, but it’d probably be terrible advice to give to most everyone else.

So yes, take the input from others. But most of all understand yourself, what your preferences are, and get started.

Speaking tip #2: Be yourself on stage 🤪

Another thing that’s tough to do when you’re just starting off is figuring out your “style”.

If you’ve ever seen me on stage, I wave my hands around like a madman. My slides are brief and have a bunch of silly emoji on them. If you’ve ever seen Mark Allison speak, he opens with a magic trick almost every time. If you’ve ever seen Christina or Huyen speak, they do live coding. I wouldn’t dare attempt either of those as I’d probably kill someone.

It’s easy to think that just mimicking someone else’s style is the answer, but it most likely isn’t. You’ll ultimately need to find a way to do things that feel natural to you. And while it might take some work and introspection to figure that out, the biggest benefit is that it’s going to make preparing and presenting a lot easier. When you practice by doing what comes naturally to you, it makes the final show on stage a hell of a lot easier.

And remember, people are there to see you, so be yourself! Of course they’re interested in the topic, but they came into that room to see you talk about it, not someone else. Be proud, be confident!

Now all that said, there are some tactical things you’ll want to avoid. Chet Haase has this great talk called “Top Tips for Terrible Tech Talks” that’s worth a watch.

It’s satirical and funny, but at its core has some really good tips on some of the tactical things you’ll want to avoid in a talk. Highly recommended.

Speaking tip #3: Don’t forget, we’re rooting for you! 🤗

This may sound obvious, but it bears repeating especially when you’re anxious on stage: we want you to do well!

Literally nobody wants to go back to the office and say, “Wow, I saw Dan completely implode on stage. It was a disaster and it was awesome!” We want to go back and say how much we learned, how great the talk was, and how inspired we are to get cracking on something new. What you as a speaker want and what we as an audience want are exactly the same.

You’ve done the work, so relax. Execute. You’re ready. And really, what’s the worst that happens? You flub a couple lines? Nobody will notice. You fall of stage? Hell, you’ve got an amazing story to tell.

And remember, when it’s over, it’s over. It’s a success no matter what because you accomplished something that most people can’t. Be proud of that and don’t look back or nitpick your work. You did it!

🧙‍ Contribution #3: Mentoring

This type of contribution is for folks who aren’t really into putting themselves out there in a public space that reading and writing demand. But that doesn’t make it any less important and valuable, not by a long shot.

So many people need mentoring, but I think it can be easy to forget how hard is to be a beginner who is just getting started. When you’re just starting out (if you can remember) you crave direction and guidance, and it can be hard to find that.

What’s wonderful about mentoring is that you can provide exactly what people are looking for. Even better, the work you put in doesn’t just have a positive effect for a few months — you’re setting someone up for long-term success. You’re establishing the foundation of how they’ll do their work for years to come, and that has a compounding effect for all the people they’ll eventually work with and mentor themselves.

And I have to say, there is nothing like seeing someone grow right in front of you, sometimes far beyond you. It’s by far one of the most rewarding things you can be a part of.

So if that sounds like something you’d want to do, here are some things to keep in mind.

Mentoring tip #1: 100% expertise is not required 📚

It probably goes without saying, but you can’t possibly know everything. But sometimes I think people avoid becoming mentors because they feel like they don’t know “enough”, when in reality they probably know plenty.

What’s more important than having all the answers is to be able to show your approach — to share how you think about things and work a problem. That’s almost as important as any answer you can give.

In fact, showing that you don’t have all the answers and make mistakes is a wonderful thing too. When beginners see more experienced folks struggle, it’s a welcome reminder that we’re all just figuring this out as we go.

Mentoring tip #2: Advertise yourself 📢

Another thing that’s easy to forget is that as a beginner, it’s hard to ask for help. So let’s flip it.

As someone with experience and knowledge to share, put yourself out there — whether that be publicly, at work, or just on a small team. This doesn’t have to be formal or some big announcement, but it should be specific. If you’re talking to someone and want to offer help, say so. Tell them you are willing to help out or mentor, directly. that’ll make it a lot easier for someone just starting off to approach you when they need help.

There’s this great tweet from Stephanie Hurlburt from a while back that really nails it:

And what’s been great is that within our Android community, we’ve had people offering this exact kind of help publicly:

It’s just wonderful seeing people in our community do this. And by the way, if you haven’t taken up Nick or Dan on their offers, you should!

And remember, there are a lot of different ways to help. No mentor/mentee combo is the same. You can offer to informally review someone’s work, go through code or a pull request, or even just sit down and shoot the shit. It depends on your dynamic and what the person is looking for.

Being a beginner is hard, so let’s make it easier on them and help build our community from the ground up.

Mentoring tip #3: Provide guidance, avoid answers 👩‍🏫

Said another way, be a teacher, not an encyclopedia. Anyone can look up an answer on Stack Overflow and implement it, but it’s much harder to understand the thinking behind a solution. And really that’s what matters.

Your goal should be to guide them toward an answer, rather than give them the answer. Giving the person an opportunity to think and problem solve is ultimately going to make them a better developer in the long run.

One of the most common, convenient ways to do this is in a pull request. Instead of offering specific code solutions, consider just asking questions. Instead of pasting in a code snippet, ask “Have you considered trying this approach” and offer up a pseudo code alternative.

Sure, there are going to be times when a specific answer is going to be exactly what the person needs, but more times than not, the path toward an answer will serve them best in the long run.

👩‍💻 Contribution #4: Open source

OK, this is the big one, the one we all rely on. Perhaps it goes without saying, but this is an excellent, excellent way to give back — you could argue it’s the most important. I probably don’t need to tell you why it’s so important, but I’m going to anyway. 🙉

First, you can make a huge impact. Obviously if you make a library that a bunch of developers use, your work will directly be impacting thousands and thousands of customers. Your impact will enormous, which you have to admit is pretty damn cool.

Secondly, and I think somewhat overlooked, is that working on open source is a powerful way to learn. At work you usually end up working on the same closed source app, with the same people, and the same patterns. This isn’t a bad thing of course — that kind of continuity and stability is wonderful.

But when you work in open source, you can learn a bunch of new ways of doing things. You learn how other people and teams operate. You learn other ways of approaching problems. You consider different factors when you’re not writing closed source. The list goes on and on. By doing something out of the norm from your “regular” work, your opportunity to learn grows tremendously.

Finally, working on open source is an instant resume builder. At Basecamp when we hire programmers, the first thing we do is ask for code to look at, because that’s the thing that matters the most (at least to start with). The problem is when you’re looking for a new job, a lot of times your old company is not exactly going to be offering for you to take their closed source code with you to show off.

The great thing about open source is that you have a portfolio ready to go. At any moment you can point to the work that you’ve done in open source and any prospective employers can immediately see the breadth and depth of your contributions. That makes you immediately more marketable.

Sounds good right? Here are a few tips to get started.

Open source tip #1: Every little bit helps 🦐

As you get started in open source, remember that your contributions don’t have to be huge. You don’t have to work on some major overhaul of a project in order to make your mark.

There are a bunch of little things you can do: fix a small issue in the issues list, update the README or fix up some documentation, or even just log a well-documented bug. These may not sound like important contributions, but they’re very helpful to maintainers. Everybody wins when you tackle some of the small stuff.

As you get more comfortable, you’ll find yourself naturally working into bigger issues and bigger sections of the code. Just give it time — starting small is great.

Open source tip #2: Discussion is good, code is great 💻

A lot of times on Github you’ll see really long discussions on how to implement something, and that’s a good thing. Discussion and discourse is usually a solid path toward well-designed solutions.

But sometimes discussions stagnate, start to get nitpicky, or just completely derail. There’s no exact formula to recognizing it, but you know it when you see it. And it’s times like that where code is great.

Code cuts through all of the noise. It’s a real implementation that can be discussed in concrete terms, not abstract ideas or theoreticals. You can bake off different approaches and determine the pros and cons of each. You can see everything in front of you instead of trying to piece together half-formed ideas from multiple people in your head.

If you’re ever in doubt on what to do on an open source project, just write code. Maintainers love pull requests and real implementations.

Open source tip #3: Be friendly and respectful 🤗

When a bunch of people are working on an open source project, you have to remember that it’s likely that these folks are spread across many continents, speaking many different languages, with backgrounds from many different cultures.

Personalities plus a thousand other variables makes interactions unique and probably a lot different than you’re used to. Miscommunications can happen. A lot of times people are working on open source on their own time. And even for those doing it professionally, it’s not an easy task to wrangle all those people and personalities.

So remember, generally speaking people aren’t trying to be dismissive or rude. More likely they’re just trying to be direct and cut to the chase. And hey, if you’re not sure and something makes you feel gross, you can always choose to take the (much harder to travel) high road and keep things positive.

Jessie Frazelle had this great tweet from a while back that summarizes it perfectly:

So that’s it — four areas that you can contribute to. I hope there’s something there that appeals to you. But if not, there are dozens of other ways to be an active member of our community. Find your niche! If you haven’t been super active before, I’d really encourage you to think about how much our community has meant to you and how much you can help others.

🎬 One year ago

The last thing I want to leave you with is this: one year ago, I hadn’t given a single talk, not one. And just a couple weeks ago I was standing on stage giving the opening keynote at Droidcon NYC.

Now I’m not saying that to make it sound like I’m hot shit or that I accomplished some amazing feat.

No, I say that to give you perspective. If you start today, who knows where you’ll be three months, six months, or a year from now. You could be the most eloquent writer, a prolific open source contributor, or a world renowned speaker. The key is that you just have to start now.

I can’t wait to see what you all come up.

Note: This was a transcription of my opening keynote from Droidcon NYC 2018 that I did from memory, so it’s not an exact 1:1 from the talk. If you want to see the actual talk, I’ll link up the video when it’s up. Here are the slides from the talk if you’re interested. Thanks!

How I built my first Android open source library (and how you can too)

A practical, step-by-step guide for building your own open source library.

In early 2015 I recognized a major hole in my professional work — I hadn’t made a single open source contribution. That’s pretty embarrassing to admit, considering I work with some major open source contributors on a daily basis.

Shortly after that depressing realization, I set a goal for myself: find a way to make at least a few small open source contributions within the next year.

As luck would have it, I knew that Turbolinks 5 would be released in early 2016. And one of the goals of the Turbolinks 5 project was to have adapter libraries for all three major platforms — web, iOS, and Android.

So having never done any open source work at all, what did I do? I volunteered to lead the charge and build a brand new Android open source library from scratch. 😳

Sure, I stumbled along the way, but in the end I somehow figured it out and we successfully launched Turbolinks Android in February 2016. 🎉

Why create a guide like this?

Creating an open source library has been such a rewarding, fulfilling experience — so much so that I want to encourage any open source newbies to give it a shot.

But hey, I get it — if you’ve never open sourced anything before, it can be a bit daunting. You don’t know how or where to start and you don’t have a map to tell you where to go.

And that’s exactly why I wrote this gigantic article —to hopefully give open source newbies some general direction on how to get started.

Keep in mind, this is based solely on my experience, and I’ve only done this once. Still, if you’re just getting started with building your own Android open source library, I hope it helps. Onward!

Step 1: Build a real app for yourself

First and foremost, build an app that does what you need it to do. Don’t worry about open sourcing anything at this point.

This is important — you don’t want to get bogged down with a bunch of questions about open sourcing that don’t matter yet. Hell, you don’t even have anything to open source yet!

Just keep building your app as you normally would. Your goal at first is to take care of yourself and make a great app, not worry about other people and their projects (at least, not yet).

And build only what you need — nothing more, nothing less. If you start worrying about open sourcing too early, you’ll start making premature design decisions in your code, like prioritizing “flexibility” over convenience and clarity. It’s not worth it— you’re just making complete guesses!

Step 2: Identify a problem your code is solving

Once you’ve got your app in a good place, it’s a perfect time to look at your code and determine what parts of it might be useful to others.

Scan your app and keep an eye out for…

  • Code you’ve re-used from a previous project. If you’re borrowing code from something you worked on before, there’s a good chance it’s doing something useful and could be bundled up as a library. At the very least, it’ll save you the trouble of using it in your next project.
  • Code that’s “your version” of another third party library. If you’ve written code that does roughly the same thing as another library, that’s actually a good indicator of a potential library. Even if your implementation is similar, how you approach the problem — your style — is what will come through. If existing libraries didn’t meet your needs, then there are probably hundreds of developers who are in the same boat.
  • Code that solved a particularly difficult (or tedious) problem set. Think about how appreciative we all are for libraries like Retrofit, GSON, and Robolectric. If you’ve solved something painful but necessary, think of how much good you can do for the community!
  • Code that is a unique solution to a common problem. As an example, Turbolinks Android falls into this category. It speeds up WebView performance by using a shared WebView, with Turbolinks doing all the work of requesting, rendering, and caching. That’s our unique take on solving a performance problem, but there are dozens of other ways to improve WebView performance too (caching, pre-fetching, mobile-specific views, etc.).

Step 3: Extract the relevant parts

Once you have an idea of what your library will do, it’s time to extract that code out into it’s own package and classes.

The goal here is simply to put together a rough outline of what the library components might be, and to see them all together. This also starts to put a soft delineation between your app’s code and what will eventually be your library.

You’ll need to hunt down all the relevant methods and slowly move them into new classes, most likely in a new package. Android Studio’s refactoring capabilities should make this pretty straightforward.

I’d recommend doing this in small pieces, slowly testing your app as you move things over a few things at a time.

Don’t get too hung up having it perfectly organized yet. Hell, you can even just throw them all in one giant class for now.

And definitely don’t worry about what the public interface is going to look like — method names and signatures don’t matter yet. Just do a “raw” extraction and get your app compiling and running.

Step 4: Refactor everything into a private interface

Get ready — this is going to be the lion’s share of the work!

Now that you’ve gone through the work of extracting the code into their own classes/package, it’s time to refactor everything. Update your method names, method signatures, dependencies, class structure. Refactor everything until you’re happy with how the library’s code looks on its own.

As you’re going along, keep this in mind: everything should click in your brain and feel natural.

Part of what’s great about building your own open source library is that it’s opinionated software. You want it to serve you and other likeminded people. So building the library in a way that fits your brain is the first step toward making a great public interface (the next step).

Beyond doing the pure plumbing of refactoring, you’ll want to gut check how your library’s interface feels in the context of your app.

If you’re on the right track, you’ll get good vibes about how the library integrates into your app’s code — readability, clarity, and the convenience it brings will all feel very natural. If it doesn’t, it’s time to go back and refactor some more.

This is also an excellent time to solicit as much feedback as you can from other programmers, regardless of their language preference. Some of the most valuable feedback I received was from Rails and iOS programmers. Iterate your code and create pull requests early and often.

Step 5: Stabilize a public interface

Now that you have an interface you’re comfortable with, it’s time to start thinking about other developers.

The good news is that you’ve done 80% of the hard work already with your private interface.

The bad news is that the remaining 20% is going about making things super stable, which means repetitive, check-everything-with-a-fine-toothed-comb work. The goal is to review every last detail of the library to make sure it’s solid.

This is the time to take a final pass through everything — naming, visibility modifiers, method signatures, every object passed in or out of your library, and whatever else you can think of.

Then test, test, and test some more.

All that said, I don’t want to make too fine a point of this. While you’ll do your best to make sure you’ve covered everything, the reality is that you’ll still miss stuff. Don’t fret — it’s software, things break. We’ll understand. 😉

Step 6: Document it

Since this is so late in the game, you might have thought you’d get away without having to do any documentation — nope, it’s a necessary step!

While I can’t say writing documentation is boatloads of fun, I did find it to be super valuable when building an open source library (I’m still generally anti-comments in private app code). Here’s what you’ll need to do.

Javadocs — You’ll want to comment every single class and method, public or private. Assume that nobody has any idea what you’re doing in the library code.

To be clear, I don’t mean you should comment every line of a method — your code should still do most of the talking. But writing a Javadoc comment for every class and method will 1) help people looking at the source and 2) let’s you to generate a nice Javadoc.

Once everything is commented, generate a Javadoc and give it a read. Look for holes and things you’ve missed. Have others read it. Does everything you wrote make sense to you and to others?

README — A good Github README does a few things:

  1. It describes what the library is and does at a high level
  2. It provides clear instructions for basic configuration and getting started
  3. It provides instructions for advanced techniques or configuration for those who are interested

I’ve found the best thing is to mimic READMEs from other libraries that you’ve found helpful. Here are a few recent ones that we’ve written that I think do a good job:

Step 7: Move the library code to its own project

Now that code complete and fully documented, you’re inching your way to publishing this to the world!

Before publishing you’ll want to move all the library classes to its own Android Studio project. This ensures the library is completely self-contained, eliminating any unexpected dependencies on your app. You basically want to see if it can compile and stand on its own two feet.

Once you’ve moved everything to a new project, you’ll need to setup a dependency to that project’s files. This is weirdly tricky in Android Studio, so here’s how to do that.

In settings.gradle:

include ':app'

include ':turbolinks' // name of the module
project(':turbolinks').projectDir = new File(settingsDir, '../turbolinks-android/turbolinks') // location of the dir

In your app’s build.gradle file:

dependencies {
compile project(':turbolinks')

With those two configurations in place, the two projects are now file linked — any changes to the library files from either your app’s project or from your library’s project will update the same files.

Step 8: Publish it!

Finally, it’s time for all that hard work to pay off!

Relatively speaking this step is pretty easy, albeit a bit tedious. You’ll be publishing to jCenter, which is the default repository with Android’s Gradle plugin. You’re simply packaging up your library in a way that Android Studio understands, and in a place that Gradle already knows about.

My recommendation is to follow a combination of the three resources below. They are pretty much step by step and walk you through the entire process of publishing to jCenter.

Once you’ve done that, your library is published. Congratulations! 🎉

Step 9: Maintenance and community relations

Now that your library is public, there will be more eyes on your work — questions, issues, pull requests and discussions will crop up. This is a good thing!

I’m always thankful that people are interested in the project and want to be involved. But there will be times when you disagree with a discussion or you simply don’t have time to address everything. That’s OK!

Maintaining a library is no small task. There’s going to be some pressure from the community to keep things moving. We all want things to be better. But it’s also OK for you to say no or to defer work. There is literally always more to work on.

The most important thing is that you keep you continue enjoying working on the library. If that means addressing all the community requests, do it. If that means saying no, do it. If that means working only on the things you want, do it. Keeping your sanity and happiness working on this library will be what sustains it for the long run.

Summary & Acknowledgements

If you’ve made it this far, you’re well on your way to launching your own Android open source library. You’ll soon be helping a lot of people by making their lives easier and their work better. Great job! 👏🏆

If you have questions about anything I wrote about or just want to chat, I’m always glad to help! Feel free to email me or hit me up on Twitter.

Also, this process is the furthest thing from a one-person show. Literally none of what I talked about above — creating the actual library and having the opportunity to do so — would have been possible without the help and encouragement of everyone at Basecamp. Thank you all!

I’d like to thank a few specific folks for their unwavering support and contributions in helping launch and maintain Turbolinks Android: Jay Ohms, Jamie Dihiansan, Sam Stephenson, Jeffrey Hardy, and Zach Waugh. ✊

See Turbolinks Android in action in the Android app for Basecamp 3!

If you found this article helpful, please do hit the heart button below and let me know on Twitter. Thanks!

To the Android open source community: Thank you!

While developing the Basecamp 3 Android app over the past year, we’ve leaned quite a bit on some really useful open source libraries.

These libraries did a bunch of heavy lifting for us. They helped shorten our development time, increase programmer happiness (since we didn’t have to write them from scratch!) and ultimately ship a better product.

Open source is such a deep-rooted part of Basecamp’s culture that I think it’s important to give credit where credit is due. I want to, in some small way, show our gratitude to a group of people who probably aren’t thanked all that often.

So, to all of you — the women and men who author and maintain Android open source projects everywhere — thank you very, very much for all your hard work!

The All-Stars

There are lots and lots of libraries out there, so I’d be remiss if I didn’t call out some all-stars that really helped us out.

Big thanks to the teams that build and maintain these libraries — you’ve made our work and lives better! (If you’re an Android programmer, it’d be a good idea to bookmark these if you’re not already using them.)

  • Facebook’s Stetho: A debug bridge that lets you use Chrome Developer Tools to inspect native UI, resources, and data. We use this quite a bit to debug layout issues and stored preference data.
  • Flipboard’s BottomSheet: An easy way to mimic Android’s bottom sheet interaction without writing it from scratch. We use this to power our share sheet, and have some ideas about future uses too.
  • Google’s GSON: Easily serializes JSON into Java objects. We use GSON a lot to serialize JSON data, which makes it a breeze to work with in Java.
  • greenrobot’s EventBus: An event bus that makes it super easy to implement a pub-sub model. We use events for all sorts of stuff, like updating the UI when a background data call finishes.
  • Path’s Android Priority Job Queue: A job manager that has simple defaults, but offers a lot of power too. It’s fantastic for running asynchronous jobs and a wonderful replacement for the dreaded Asynctask.
  • Square’s Retrofit and OkHttp: If you’re doing any kind of API or HTTP work, you need to use these, period. We use Retrofit exclusively for all of our API interfaces.

Giving Back — Turbolinks Android

Like any good citizen of an active developer community, we’re not just going to leech — we’re ready to give back!

In short order we’ll be releasing our first open source Android library — Turbolinks Android. It’s the same adapter framework that’s powered our Basecamp 3 Android app since November 2015, and it’s a crucial component in our native-web hybrid approach. It’s made specifically for Android, and will get your hybrid app hooked up to a Turbolinks 5 web app in a jiffy.

We’ve done our very best to make sure Turbolinks Android possesses all the qualities that we love about the all-stars libraries above: easy to get started, easy to use, fast, and reliable.

We’re thankful that we’ve been able to stand on the shoulders of awesome libraries ourselves, and can’t wait to get Turbolinks Android out to the open source community!

If you’re an Android open source developer and ever want to chat, feel free to contact myself or Jay. We’d love to talk and share ideas!

We’re hard at work making the Basecamp 3 and its companion Android app the best it can be. Check ’em out!