00:00:16.789
I'm also setting my coffee down. Before I get started on the talk, I just want to say that this slide does not refer to veterans from our US military—who serve for our right to have a voice, even when that voice is against the country they serve. That's pretty awesome. So, since I'm up here on stage, I just want to say thank you to our US veterans. Whether they see combat or not, they put their lives at risk when they enlist. Thank you. I am honored to be in a community with those who have served. However, this slide does refer to everybody else, but especially to me, since it faces the goat. It should surprise no one that I have a little bit of content warning. I will occasionally use so-called curse words, at least on my slides. I did my graduate school work in English just up the road at the University of Cincinnati and I have a healthy respect for language and words. I do not mean to offend anyone when I use them, and I hope you still get takeaways in spite of my horrible language.
00:01:05.000
I know you folks came here for some kind of talk involving goats, but I'm going to start with cattle, or cows, as they're colloquially known. Regardless of gender, I know all those things. So, last month, I was doing a road trip through Washington, Idaho, Montana, and Oregon. In fact, I got the call about being a keynote while I was in the hills of Montana. The phone actually cut out, so I'm thinking, 'I think I'm a keynote, but I don't know.' Anyway, we saw a lot of cows, and I'll just skip to the end: I decided I wanted to pet a cow. I found an accessible field, and I went out to the field only to discover that these were not the lady cows designed for milking, as I had thought they were. There I was, surrounded by cows with my friend filming me, and I got out of the field slowly.
00:01:59.000
Later, at a diner, I did what we all do, which is Google for information about what all these cows were up to. I found some information that kind of blew me away, and I thought, 'Oh good, I'm going to be on a big stage. I get to share this with everybody.' You just have to hear about cows so you won't know what you don't know. What I did not know—and maybe you are in the same camp—is that an ox is not an animal unto itself. Did you think an ox was an animal? It’s not; it's a role. Just like any note, no animal is born being an ox. I had no idea! I played Oregon Trail my whole life. Oxen were pulling the wagon, and I had no idea that an ox was not an animal; it’s a role. It’s a cow trained to be a draft animal.
00:03:02.189
By 'cow,' I mean again, all genders; but your lady dairy cow can be an ox, but no one is born an ox. That’s just crazy to me. So, hopefully, this is news to you. Even if the rest of this talk does not go well, you now know that an ox is not an animal—don’t spread that rumor anymore. But don’t worry. Even if this is not news to you, I’m totally going to use a horrible analogy about this later. Spoiler alert: it’s going to have to do with your ability to be a code cow without—you can still do the ox’s job of being a documentarian while you are a code cow. That’s awesome, but frankly, I’m still pretty blown away by this information and now you know.
00:04:11.939
My name is Tara Scherner De La Fuente. You have the empathy of a goat, and I will be talking about documenting with the user in mind. I am a software engineer at Roostify, a tech company based in San Francisco, where we're making mortgage buying awesome. No, really, it’s happening! I am part of it and I work for my office in Portland, Oregon. By home office, I mean in my living room with my cat. My Twitter handle is @mediaremedial. That’s back from when I did more things with words. I want to point out it's not on any of my slides because a lot of the images and content aren’t mine, so I don’t brand them. If you want to tweak, go wild! So, that’s where it is up there. Speaking of animals taking on roles, when I’m a goat, I tweet about goat user stories. I have stickers that look just like that, by the way. I also have Roostify stickers I put over there for afterwards. If you aren’t familiar with goat user stories, I do a traditional user story each day at 10:20 a.m. Pacific Time. It follows the traditional format of 'as a user, I want to so that...' and my user is always a goat.
00:05:03.510
Sometimes it’s serious, sometimes it’s not. Sometimes goats just have problems they need to share, so that's what that’s all about. Okay, so now we have the user and documentation. I’m going to make up a statistic now: let’s say as developers, about 80% of our job is working with text, so documentation should not be as avoidant-worthy as it tends to be. However, even with my sort-of overworked English person self, I don't want to stop building things and solving problems to do documentation. This talk is geared toward discussing good documentation that’s built into our processes so it feels less like putting on a yoke—for you know, the oxen reference—and building that into our dev process.
00:06:12.040
First, I want to talk about the user. This is nothing new: the user is in the mirror, especially the user—you, the user three weeks from now, five weeks from now, when you no longer remember that awesome code that you built. The user I’m talking about today is future us—your fellow developers, those on your team, those elsewhere in your company, other developers who are using your code, stakeholders, and clients and customers. They are really the folks that you’re usually interacting with on a day-to-day basis and you know they are the reason we have jobs.
00:07:11.819
Next, the documentation. I’ve put some examples up there. I’m not going to focus on formal documentation; I'm speaking about documentation found in code, in Git commits, in pull requests, and in other types of documentation that we actually run into and read and use daily. I love this image. I send this image to my friends when they're promoted to management and you can already suspect why, but I congratulate them: 'Mazel Tov on moving into management!' I am Jewish, so I say 'Mazel Tov,' but you can say it too; it’s awesome! Then I'm like, 'Here’s your box full of meetings!' No matter what Rubios tell you, comments in code are not the enemy. I know that’s horrible to say and may not become true, but it is. Meetings are the enemy—at least in my opinion—and it’s my talk, so that’s what we’re going with.
00:08:03.150
Good documentation is not only empathetic to the user but it also helps avoid meetings—which is my goal for you. If no one has to ask you a question about why you did something, in what way, and how the behavior changed, you get to keep coding and building the fun things. That’s the goal! Most of us are paid pretty well for our knowledge, experience, and ability to code fast. Hopefully, writing good code at a good pace is one of the ways we earn our keep. Another way is through clearly communicating what the user needs to know so that they can use their knowledge and do the next thing, whatever that next thing is.
00:09:12.140
Even if your team is only you and future you—which I particularly thought about yesterday during Matz’s talk when he was just 1993 and he was the only user—future Matz was also on the team. I have purposely resisted asking him what his documentation was like back then because I didn’t want my thesis to be proved incorrect before my talk; I’ll ask him later. In any case, even if it’s just you and future you, documentation is crucial because it can help speed you up and keep you coding rather than having to explain or under-explain when somebody needs to go. That’s the two sides of the curse of knowledge: explaining and under-explaining. Neither serves you well; both are going to have you ending up in meetings.
00:10:01.300
If you assume that most of the people reading your code know the underlying concepts and tech details, you might have the empathy of a goat, and not in a good way. Let's say they can read the code and know what it does, but even the best code cannot explain why it’s there and what it’s doing there. If it’s unusual, if it’s implemented to solve something surprising, or if it behaves in an unexpected way, understanding the code isn’t necessarily enough. We’re already users of people’s documentation when we’re coding. I mean, does anybody get through their day without Googling? I do not! The kind of stuff that we benefit from when building the code is the sort of documentation we should be contributing, and that’s what I’m hoping to encourage you to do.
00:10:53.000
If we document things, maybe we save other people time. It doesn’t have to be read-commented, and maybe you save time and ideally have fewer meetings. The flip side of the curse of knowledge is over-explaining—which I may have done with livestock earlier. It can become an overwhelming amount of information that no one could hope to parse out; that’s one of the curses of knowledge. However, it's at least a start, and I will talk about how to recover from over-explaining unless you’re doing a talk. The first thing you have to do is find those user stories that I mentioned earlier about the goats.
00:11:51.890
While looking for an image for these slides to prove a point, I found all kinds of inspirational quotes on the internet, which is no surprise. This one states: 'If you only focus on the problem, you might miss the easy solution.' That sounds totally logical, right? But what if getting out of the crate is not the cat's problem? As far as it's concerned, what if the crate is just missing a blanket or it's trying to stay away from a mouse or a toddler or something? You need to start by identifying your user, who again might just be future you. But then you need to identify with the user. One of the best ways to do that is to focus on the problem, not the solution, just in case that wasn’t clear.
00:13:02.880
One of the most valuable things I ever did as a developer was watch an end user—in this case, somebody internal to the company. What she wanted was a solution to a CSV loading problem. Now, if you have ever worked with a CSV loading problem, you know that I could possibly solve that one, but another one will come. So focusing on the solution and what the user wants is not really going to help me much. I watched her upload the CSV and show me how that all worked. I sort of sat there, blown away, observing all the things she had to do. She was leaving out tons of details; there were dates, times, and other things in the CSV that all needed to line up to other things already in there. If not, she had to use a pulldown list and find the thing and line it up. Oh God, it was awful.
00:14:05.120
Every time there was an error, she had to go into this pulldown list which was not even sorted. So there were about 50 dates, and she was looking for something on December 17 at a certain time. There were a bunch of December 17ths along with others in December. It was horrible! Then, she had to do it twice because someone left an equation sign on the view page. So the poor woman had to go in there twice and fix that. She didn’t even care about that—it wasn’t even the problem she had in mind. However, there were more problems on the other pages; she couldn’t save one page and move on to the others, and she didn’t even consider that a problem. But those were things I could totally fix real quick—in less than an hour! At least now, when she has a CSV loading problem, she can save things and then move on.
00:15:02.700
If you start with what they want or the solution, you could miss improving somebody's life exponentially each time something goes horribly wrong. So if you can watch the user—even if it’s a fellow developer who’s verifying that your code works as expected—this is so helpful to know not only about code design but also about what you might need to explain either in the code or in a git commit. If you can get a product manager to screencast somebody using the app you’re building, so much the better, and you’ll find out what questions everybody has and what information you need to convey. If you can rock being one with the problems, you will be that much more alert to empathizing with the user. Oh God! Just think of saving that poor woman from all those horrible pulldowns! It’s awful!
00:16:04.820
I hesitated to bring up commenting in code to a bunch of Rubios, but I’m going to do it. It should be easier to grok with a coder and their possible problems, but old code is Old English, and it’s not right for every project. If you’ve got some kind of method—for example, say you're putting in care code and maybe it’s going to be short-lived or it relies on a particular version of Active Record—this is something that perhaps someone could remove in the future. This particular comment is an actual comment from code, including line three. This was only three lines, but I had to bump up the punctuation, that kind of thing. God bless Sam Livingston Gray, who writes the best comments in all of development that I’ve ever read! And it explains clearly why this method exists and what it's trying to accomplish.
00:17:18.100
If you come across this comment written in code, it’s important to know that we were in Active Record, and this is no longer an issue. Maybe we can remove this method and make things work traditionally, leaving line three behind because it’s funny. This is the kind of thing you might want to document in code because it’s not about how the method works—we can read how the method works—but why it exists in the first place. This could easily be removed later. You’re not going to think—or at least I wouldn’t—especially if I’m in an app that’s several years old with tons of developers. I wouldn’t think, 'hey, this is an unusual method; I should look and see what the original commit said.' Probably it’s been refactored and changed over the years, and likely, nobody brought that information across through all the commits.
00:18:10.000
I wouldn’t—I'm lazy! But if there’s a comment in the code, it’s accessible, right there. It’s potentially short-lived. If that problem goes away, these are great attributes to comment about in code. You want to explain the why and now I want to talk about commit messages. I’m going to cover rudimentary parts because why should we assume that everybody knows good practices? If you don’t have a traditional style like I do for my commits every time, maybe incorporate this. You want to explain what happened, why it happened, and how it happened. How is more like what you talk about over beers later on.
00:19:02.740
In a great commit message, you want to cover the things perfect code cannot explain. Some practical things for a commit message: the first line of your commit message—that’s going to appear in your git log—should be concise: start with a capital letter, it does not have a period at the end, and keep it under 50 characters. Skip a line; this is important! Then explain the what and the why. Discuss anything unusual. Make a note of if anything has changed, and if baby seals are going to be clubbed, note that too—it's very helpful information. If there’s documentation on the implementation include a link; you can include bullet points with hyphens if you’ve got an issue you can link to with a conversation on board.
00:20:00.700
I will say don’t rely on automagic services. If you can have a direct link to something like that, that’s good. We’re moving on from that! I know this is review for many of you but a good commit message is part of documenting as part of the dev process. A good commit message does not take much time and this text can be copied later—it's awesome! Let’s say you’re not that ambitious. One thing I didn’t cover on the last slide was the format—the tense. There’s an official name for that—it’s like imperative or declarative or something. I just always think, 'this commit will...' and then what follows is the commit message.
00:21:01.970
You can do 'git commit -m' for message and put it right in there without any explanatory stuff. It’s kind of sad, but that style I sort of think of as a condensed user story. So if you can figure out your user, write 'as a user, I want to do this so that...' Maybe the user wasn't enabled before, so that’s important. Now, they can do that. If they couldn’t send a goat message before, now they can! What’s changed, and why? This sort of encompasses this. It’s not a great example; you can do better, and that’s the sort of thing you want to do.
00:22:08.240
If you have done a good commit message, well, if you use GitHub and use it for PRs, it will all translate up to the GitHub. If you’ve done this well—especially that line-skipping thing—it will appear up there. Then, you can address company-specific things that you do. Maybe you do some of that automated stuff. At one of my last companies, we waited until we were in the PR stage to add who we paired with, which kind of documents non-driving work and gives credit where credit was due. Again, the idea here is to make documentation just an automatic part of the experience.
00:23:30.350
Ideally, you’re crafting code that is easy and obvious for the user to use, but it won’t be obvious to everyone. Maybe it’s not right now; I’m at a company where we focus a lot on compliance and security because it’s the mortgage industry. It’s really important. A lot of the documenting we do has to explain through audits what we do and why, and we have to justify the changes that we make in the code. Sometimes, I’m writing for a security person or a financial person, and that’s important to consider when writing these commits and PRs. You have your own context and users you’re writing for, so it’s not going to be obvious to everyone.
00:24:23.520
If you want to avoid meetings about explaining to the security person why you made this change, document what changed. Comments are not the enemy, and if I haven’t been clear, meetings are the enemy! You want to comment where necessary and helpful and write a great commit message. Depending on what needs to be written, you may feel self-conscious about some of your writing; I have some practical writing tips for you! I know you're excited; I can tell everyone loves this documentation!
00:25:12.600
This is an excerpt from Anne Lamott’s awesome book, 'Bird by Bird'. She writes about writing, and this is a quote: 'Almost all good writing begins with terrible first efforts. You need to start somewhere. Start by getting something—anything—down on paper.' If you’re one of those over-explaining folks, at least you’re getting started! I want to reiterate that I’m talking about anything you might feel self-conscious about writing, and that includes commit messages, Stack Overflow answers, or a lovely rake task that makes lives better. I don’t care what it is; if you’re unsure about even getting started, just write a shitty first draft! For the love of all things holy, the hard part is getting that first draft down.
00:26:12.640
But the first draft writer is the unsung hero; the best writing is rewriting—we know that! You can be the writer and let the rewriter get all the glory. You will be a hero to the rewriter if you just put it down, and they will know how awesome you are for having a place to start. Just take the leap! I couldn’t help but take the leap. Never say there’s a goat I write, yeah? Just don’t think about starting; just get started. Now, I was an English major, and I’m really not a Shakespeare fan, but here are practical tips for most of your documentation.
00:27:21.820
Just some practical writing tips. We can't cover it all, but write shorter sentences; don’t try to sound sophisticated—nobody wants that! Avoid jargon and acronyms. This goes back to having empathy for the user. You're not writing only for future you—you're writing also for people who don't understand all the things you’re including. If you can spell out an acronym—you see, CI stands for lots of things. Sure, 'continuous integration' sounds nice, but it doesn't always mean 'continuous integration.' Write that stuff out! Avoid jargon. Picture the context and the likely user. Even if you're Matz, consider that there's you and future you, but later there are millions of Ruby users. Let’s imagine he wrote documentation with us in mind. Writing is thinking for me; I write as I think about the process.
00:28:58.320
I asked a technical writing organization for advice that I should give to a room full of developers, and here’s what they said: many of you will over-explain yourselves all the way to the main point. Move that sucker up to the top! You don’t have to edit out the stuff that got you there—but please, if you can just move it to the top—that’s what they asked me to share with you and is what I used to tell my composition students. They would get to the thesis, and I would say, 'that sucker needs to be way up here!' Then, you write the stuff that supports that. Please, if you write your way to the main point, move it up! Edit it out if you can, and use specific examples; that’s really the best writing advice I've got.
00:30:09.260
Now, here's the secret to writing: don't let feeling not good enough stop you from writing that shitty first draft. Crappy first drafts are fantastic! All writing requires rewriting, so be okay with writing that first one. Maybe future you can edit it, and that will be awesome. You're going to do great with that. Let me be honest—this last section is about miscellaneous stuff. I hope to get to some recap and stuff about being famous and making money if you're into that kind of thing. The best way to get good at writing is to do more of it! Here are some more ways to practice: write install instructions and ask one of your fellow developers to follow those instructions and see what you missed. Find out what you missed! Offer to follow someone else's instructions—take the second draft. Remember, the second draft is awesome.
00:31:22.600
Update your README. I signed up for something called docs.dr.org—anybody here familiar with docs.dr.org? Oh my God! Here’s what needs to happen: you go to docs.dr.org, and this is all about all the things that are not documented out there in open-source projects each day. You don’t have to do it frequently, but they send me two pieces of code from Ruby and Rails that are not documented, and suggest you might want to be the one to do that. One day, I submitted a pull request for some documentation to Rails, and they said, 'hey, you know what? Turns out that code doesn’t work like everybody thinks it does! Would you like to deprecate that and remove the code?' So, I became a Rails contributor! If you work at LivingSocial, you know I bragged about it profusely—especially because I was in the release notes right above DHH! Yes, it was awesome.
00:32:44.740
If you think being able to say that I'm a Rails contributor didn't lead to job interviews, negotiations, or salary increases, you are incorrect! That was just because I tried to do documentation. That’s how I got my first two PRs in Rails! If you're using this open-source stuff, contribute to it! You can document it. Docs.dr.org is a good start, and you can sign up for tons of different projects. I just chose Ruby and Rails for reasons that should be clear given where we are. Write blog posts! Saving someone! How many times has a blog post saved me? Oh my goodness!
00:33:46.460
It certainly adds up! Publish a tutorial. Even a YouTube one where you do a screencast for something. Reduce costs by saving future time figuring these things out! Give a conference talk about a horrible problem you ran into! Two years ago, I gave a conference talk about this awful Strong Params thing—oh, God, it was awful! I contributed to the documentation out there on the Internet too. If you search for specific problems and run into help, one of my issues contributed to the development of—not by me, but by Andrew Hunter, I believe at LivingSocial—the Ruby gem called Strong Like Bull! This happened because I kept screwing up with my strong parameters and kept blowing up the app I was working on. They would say, 'Tara’s parameters are strong like bull!' This is totally tied up with ox! I didn’t even plan that, but now the gem is called Strong Like Bull! It can help you set your strong parameters.
00:34:55.880
Documentation can lead to Ruby gems—and all the things! It’s great! Justify a salary increase by the amazing time you’ve saved solving problems. That’s awesome! Some of you may recognize this; it’s a little faded out but it’s the loading animation for Slack. I wanted to bring this up because conversational documentation is awesome. You’re not trying to document anything; it’s part of your dev process. You put something out in the room and people try to sort it out. Eventually, there’s a solution! If you pay for a service like Slack, you’ve automatically documented the problem. You pay for Slack so you can search the archives—that's why you want to pay for Slack. If you’re not doing that, we’re paying for whatever service you use! Document it! You don't have to keep everything outside; just leave it in Slack and find it later!
00:35:58.580
So automate those documentation steps! Since I’ve got Slack up here, this is an actual release note from Slack. I saved this because, first of all, some of your commit messages and PR messages can become release notes. It's also a good reminder that your personality does not have to leave just because you're writing official documentation. This is a good example of that. Yes, Sam Livingston Gray's commit messages are so sad you all don’t get to read because oh, there was one about the Pope, and it was great.
00:37:06.440
This is actually from Eric Hullinger, who is the head of Write the Docs, that technical writing organization, and I’m going to quote him: 'If people don’t know why your project exists, they won’t use it. If people can't figure out how to install your code, they won’t use it. If you have no users, people won’t contribute to your open-source project. If you have no documentation, you will have no users and you will not get contributors.' So if you are working—many of you are working with an open-source project, and you want to make Ruby great again and be stronger together, as Matz says—not any political candidate—then you want to contribute to the documentation for Ruby and build this community.
00:38:41.800
If you are the first to document something—like the crazy strong params thing—although that didn’t lead to fame and fortune like I’d hoped, if you are the first to document something and it becomes useful, it could become widely used and you could become famous! If that's kind of your thing, you could go write a book about something related to this! You could write your own book just on your own! Neil, you’ve written books! Talk to the people; tell them how to write a book later—not right now! You could tweet about oxen or something, and the Ox User Stories are totally available! You could be doing all kinds of things to use your writing to elevate your career and whatever the heck you’re doing.
00:39:53.920
Look at this goat! Oh, I love goats! I love goats! So, a quick recap: focus on the problem, figure out what the user needs, not what they want; write the shitty first draft; explain the why; move the main point to the top! For all things holy, move the main point to the top! Future you might be the user, so be good to yourselves, and rock your user as a goat! That’s all I have other than stickers and information about Roostify over there. Thank you very much for your time and attention or documentation! I'm not sorry that I suggested comments in code; it's good for you!
00:40:59.960
If you have any questions, I can answer them; otherwise, you just get out early and nobody ever minds that! Do I think some of the advice I gave applies to writing software? Absolutely! In fact, if we go back to my made-up statistic about 80%, of what we do is indeed write text! I tried explaining to my dad what I do once, and he said, 'So you’re a typist?' He’s not wrong! But absolutely, I think about text or content as the stuff I’m conveying in words but also the stuff I’m conveying which, in some ways, is the software—what they see and how they use it!
00:42:00.000
There was actually someone else! Yeah, why all the goats? People ask me that; it’s okay. I’m on stage, but do we want to do all that? I’m staying at my friend’s house, and she has a metal goat outside called Sookie! One day, I was walking by, and I was like, 'Hey Sookie, how’s it going?' because I talk to myself and inanimate objects! I laughed all day long at my awesomeness because I’m a nerd! I laughed all day, and it inspired me to start liking goats because it amused me so damn much. Years later, I lived two blocks from a farmer's market, and they advertised that goats were coming! Oh my goodness, this is exciting! So this is my chance! I could hug them!
00:43:25.000
I asked if the goats would mind if I hugged them and they said, 'We love the goats! We would love for you to hug them!' So, I am now the official goat hugger of J.K. Goats in Damascus, Oregon! I’m allowed to refer to those goats as my goats, which is fantastic! I now hug goats regularly, but I started liking goats after I joined LivingSocial—talking about goats, goat puns, and all! It was a fantastic time! Someone in the office drew a goat on the whiteboard. That became the office goat! Then Matt Robinson, who was our DevOps manager at the time, said, 'You know, we should do something like cat user stories on Twitter, but with goats!' So the whole team listed some goat user stories, which was hilarious!
00:44:46.000
Of course, lots of things about branches come to mind with goats. Low branches! As is now a tradition, we developed a Slack room for Goat User Stories. The goal was to 'overtake' cat user stories, which is no longer happening. Who would’ve thought we could’ve overtaken cat user stories on the internet with goats? But we did! This was a team effort that put together Goat User Stories for a long time. Then Matt kind of gave it up for a while; it was me and Matt, then Matt left and handed over the goat reins to me! I became the full ability to do it, and I am sorry I overexplained that, but I'm on stage—what the hell!
00:46:00.000
You can ask me any questions or—oh my goodness! It’s all syntax! By the way, she’s an English major, and she wants to know how to make other people in the humanities code. Well, first of all, there’s the money! Right?
