Session Transcripts

A live transcription team captured the SRCCON sessions that were most conducive to a written record—about half the sessions, in all.

How can teams build a consistent culture of documentation?

Session facilitator(s): Kelsey Scherer, Lauren Rabaino

Day & Time: Friday, 4-5pm

Room: Innovation Studio

Lauren: If you all end up being the only people here, you’re all going to have to group together, to do one group activity:

Kelsey: I feel good about that, Lauren.

Lauren: What?

Kelsey: I feel good about that. I feel good about that. You can be really focused.

Lauren: Hello! Thank you for sticking with us for the very last session. And I know there are a lot of good sessions happening at this hour so I’m incredibly appreciative of you being here. So we’re really excited about documentation and I think if you’re in this room you do, too. My name is Lauren row.

Kelsey: And I’m Kelsey designer on the storytelling studio.

Lauren: So a little bit of context about why we do spend so much time thinking about this at Vox. Especially our team is one that is incredibly cross disciplinary. So like many of the teams that you probably work with, we have engineers, designers, editors, analysts, project managers, people from all different parts of the organization, who speak in different languages and need to have a sense of shared literacy, around a lot of the stuff that we do. We also work with many different departments and we have a unique challenge of having eight different brands that we work with, so they all have their different goals and ways of interacting with our team in different ways. We’re also working on multiple projects at a time. Small projects, big projects, in a very fast-paced environment, so these are all probably problems that you all have, as well, but we’re not going to stand up here and talk to you. We have a lot of opinions about documentation and the best way to make that happen and be a part of a team culture, but Vox Media is—it’s become very clear at this conference that we are in sort after different sphere of operation than a lot of people and what we have to share about this is not going to be directly applicable to the way that your organizations are structured and the people you have to put behind stuff, so we’re—we’ve crafted and user-tested a wonderfully designed activity arc for you all to participate in, so the people that are sitting at your, tables, those are the people you’re going to be working with. But we we’re hoping that you all, together, can sort of define what this means for you all, and walk away with a good plan for how to make this happen. So Kelsey is going to talk through goals and first activity.

Kelsey: Yeah, so Lauren touched on this a bit, but the ultimate goal is for everyone to be able to walk out of here and understand the importance of documentation for your team, whatever that means for you. And be able to go back to your team and advocate for like it’s important, and maybe, like if we’re being ambitious, start a plan and like, go back to your team and be like this is how we’re doing it and this is what we should do or maybe we should do this. Just going to jump in. Like Lauren said we’re going to group you with your tables, we’re going to do lots of sketching and sharing within your group, but no real, like, share with the whole group. So get comfortable with your friends. The first ice breaker activity is going to be conceptual sketching. So each person, for two minutes, I want you to sketch two different scenarios on paper wit sharpies or pens or whatever is at your table and we’ll set a timer for two minutes. Draw the time that you felt really clear about what you were doing, and it can be really fast, like a really quick sketch, and then also draw a time where you had no idea what you were doing, like, absolutely clueless, everything is confusing and terrible, and sort of draw those two scenarios really quickly. You have two minutes. And go.

[group activity]

Lauren: And if you forgot what we said, there is an instruction sheet on every table. If you were like tweeting or something.

[group activity]

45 seconds left.

Lauren: Time! OK. Time’s up. They didn’t have to be works of art. Although it looks like some of you got really into it. Everyone’s now at each table choos note-taker. So we’re going to do about 8 to 10 minutes of this, so make sure you account for timing as you go around and share, but share your drawings, talk about what you drew, and like the defining point that made one scenario different than the other and the note-taker should just write down the themes that are discussed. Go![group activity]All right, so it seems like you all got through that activity. I’m not going to have you share back, because I’m tired of doing that today. Even though this doesn’t soom directly related to documentation, hopefully you’ve tarted to think about some of the things that contribute to your sense of understanding, your understanding of purpose and clarity and knowing the difference between when you do have that sense of purpose and when you don’t. So next activity,.

Kelsey: Yup, the next activity is meant to built on the previous one, not directly reled but we’re going to take ten minutes and do a group brainstorm but for this session you’re going to use a big piece of paper and maybe have a different note-taker from the first time. So this one has a scenario. Imagine it’s your first day on the job and no one is around to help you. Or tell you your project. Imagine, it’s never happened before. So.

[laughterYou’re loading your desk. Fast forward to the end of the day and by the end of the day you have a clear sense, magically, about what your team is, like your role, and also your first project. So as a group, write like—write down and brainstorm a bit about what like, on earth, was in the documentation that you were given at the beginning of that day that no one had to help you get a clear sense, and focus a little bit—you’re going to have ten minutes, so focus a little bit on the team role so you have a clear understanding of the team and the organization, but also on like specific projects, so you’re starting your first project.

Lauren: Yeah, and also consider different types of role that might be on a team, engineers, designers, content managers, like consider every type of role that might be on a project like that. Go!

[group activity]

Just quickly walking around, a lot of you focused on HR stuff. I would push you to when you’re done with the session to also sit down and think about the actual project process, like there’s lot that goes into doing one individual project, like who are our touch points, like, who gets to make a decision, what is the process, how often do we do design reviews? Where do we talk about the project? There’s a lot of nuance that goes into just getting things done that we should also think about documenting.

OK, so the purpose of that was just to imagine how we could all work together when we are our best versions of ourselves and I hope you have now pictured your ideal self and your ideal documentation set, but that is very hard to do, like doing all of this stuff written down takes time and effort, so Kelsey is going to introduce the next piece of the session, which gets at that.

Kelsey. Yup, so the next piece of the session is real-world ideas. Like Lauren said, it takes a bunch of time and effort, but there are some ways we can brainstorm together to have like some axial takeaways from the session. It’s the final group project. So for five minutes as a group, on post-it notes, start to think about how might we allow our team to collaborate, to create documentation. And then there are a couple of like leading questions that are also on the worksheet, but that’s like where does it go, who writes it, when do they write it, how do they update it? And where do they store it? Like, where does it get put and do certain documents go in one place versus another?

PARTICIPANT: So just some really actionable ideas that you can brainstorm and you can have multiple ideas for each of these questions, so we are going to do that for five minutes. As a group. I said as a group.

Lauren: Whatever way you want.

PARTICIPANT: Kelsey: Do you—OK, OK you can do it as a group, but everyone can have their own ideas. I’g to start the timer.

[group activityLauren: Time is up … Stop talking.

[laughterPARTICIPANT: OK, so I know I promised at the start that I wouldn’t make people do a group share with everyone else, but I’m seeing a lot of good stuff that I think it would be fun to do, but so I’m not going to make everyone do this but just in terms of the questions we outlined, consider it goes. Does anyone have something that stands out to them that they think everybody needs to know, I said documentations.

PARTICIPANT: We said that it was really, really important that there is like a canonical, globally accessible place for documentation, but maybe be flexible about when things ends up there because we’ve all thrown stuff in the Slack channel and thrown stuff in Google docs and somehow it’s better to capture it somehow than not capture it because of whatever friction that is to get into a global documentation, but there should be thi bullseye about where this lives.

Lauren: What about the next question, who should be writing the documentation?


PARTICIPANT: Gentleman yeah that was exactly what I was going to say. I think that everyone should be writing it. It’s too much to place on one person, and so we discussed doing a collaborative of Google doc, like operations or something like that, where as a new person is learning, they have leeway to actually make chan so that if the documentation isn’t helping them, they can then go in and fix it as they’re learning about the processes to make it better.

PARTICIPANT: So I think win counterpoint to that this I struggle with a little bit is that when everyone owns something, no one owns it. And I think that there is this—I think it’s true, yes, everyone should be doing this, but that requires lots of structural changes to the way we do our work and the way we spend our time and there have to be people who can champion that in leadership positions and say that this is actually important and you need to spend time on it and it’s not something we’re going to say oh, it’s 5:00 on a Friday, why don’t you write some shit down for how you do your work this week. Because like you don’t want to do that.

Lauren: Yeah, so I think that speaks to having an owner/facilitator to actually assign. Did anyone talk about peer reviewing? That’s something we think about a lot because there are many ways of doing things and often when you’re documenting something like process, for example, people have differing opinions how to do it which is why it’s good to document it. Think about who reads this, how do they revise it, it’s basically user testing your documentation, right, to make sure it’s clear for yourself, for stakeholders. What about when to write it. Throwing at someone 5 p.m. probably isn’t the best way to do it, it should be built into whatever structure you have. Any opinions worth sharing? I can talk about what we do. So you want to?

PARTICIPANT: I can. So we don’t have a lot of—in my team we don’t have a lot of process and we don’t have a lot of structure because everyone is coming from very differen back disciplines. So the process I try to encourage is for people to write personal docs every day to get in the habit of thinking about what they learned that they didn’t know before, that they had to look up, and how they would share that, even with their future selves. And then it—I think that’s sort of like an incremental step towards getting people ready to document things in process, or post-process. But just getting people able to identify what something is that needs to be documented.


PARTICIPANT: I think if you’re doing programming or engineering, the—there’s some differences of opinion about this, but especially if it’s something that you’re going to have—you’re going to monitor use later or somebody else is going to need to fix later, the time to do it is when you’re doing it, like commenting your code well and making sure that it’s easy to not do it because it’s becoing a laborious process but making sure that this is what’s happening in this block or this is cribbed from this project or that project and pointing to other directions and then as you’re going along, adding those comments in, there’s times when I haven’t done that and I increasingly do do that over time, and now I can copy my stuff so much easier and jump back into it. But as a programmer when you’re a project you understand its flow and how the functions are working together. But once you leave that and you’re going back into content writing or going into something, another discipline and you got to go back into that, it can be really, really hard to read what you wrote before, and I’m like, what the hell did I do? Why is there four loops in the middle of each other. So comment your code.

Lauren: Yeah, that’s a really important piece of it is commentating your code.

PARTICIPANT: Really quickly pigging backing off of that, I’ve also learned to like, especially when I do like analysis, I try and like I’ll li back to the page where I found the formula or something, because I find that that’s helpful for, like, other people to think and understand, like where I got the idea from.

Lauren: One thing that we’ve found is when you try to say, hey, this week try to document that thing, that that always falls off people’ radar, because the more important things will always trump that. So what we have we’ve been doing for about a year and a half is doing regular documentation days where it’s a required day, nobody is doing any work, but sitting in a room together, documenting like headphones on, peer-reviewing each other’s stuff so that you’re forced to do it, you can’t just let, oh, this bug just popped up and I have to do it and I can’t document right now, because it’s really easy to let that be a last priority. Another idea I’ve often heard is—I’ve talked about this with people, is just building into a sprint if you’re on a sprint cycle so like Friday every two-week sprint is documentation day.

PARTICIPANT: I was going to say we’re definitely talking about product development cycles and documentation therein. We were also talking about you know, sometimes you’re just talking with your colleagues or your coworkers about what’s working or not working or other things like that where it’s not as regimented or process-based so I think it’s important to think about what’s working even if it’s not formalized or something, and just write it down or something like that, and take the extra time to think about it, yeah.

PARTICIPANT: We’ve actually—we’re very project based and at the end of each project, just sort of it’s like our version of a sprint, we have like—and we have a really small team, but we’ll do basically we’ll basically do that as a group, like what’s working and what can we do better next time and then any other sort of things and that’s really helped husband keep track of where our own claims are and where our thinking is.

PARTICIPANT: Yeah. Something else I just remembered. I don’t know where. I think it was BuzzFeed maybe or something. Somebody tweeted that one of the organizations in Slack, any time something is said or a question is asked that should be documented there’s like an emoji that you can respond to it with or a keyword that you can use so later you can go back and search and like see everything that was flagged as that.

OK. We’ve touched on a lot of the things. How often, how to update it, where to store it. Does anyone else have any—was there anything like really clarifying or really surprising to you out of this that you want to share?


PARTICIPANT: All right, I think one point that I will definitely take away from this is how to organize your docs, so Justina was talking about how they have some pinne high-level docs, so if somebody wanted to get an overview of a project or you’re trying to onboard somebody, wherever you’re storing your docs, and then you have your working docs and another point that she made that I really appreciated was that sometimes documentation is not going to live past you writing the doc and it’s a way for you to get your thoughts out on paper and process exactly what doing a project in certain tasks means and is, and yeah.

Lauren: Good, awesome. Any last thoughts on this before—Rebecca?

PARTICIPANT: So one of the ways that we discussed documenting ising screen cast, actually as a problem comes up, so that you’re capturing the issue and your solution in the background and you’re not taking time away from creating the solution, but that is still a good resource, so that you can go back to later, or even like fast forward it so you can have like the highlighted parts for others to use if they also come up with that same issue.

Lauren: Are there any other questions or any other things we want to discuss? OK. So that wraps up our little series of activities. So the way that we’ve been thinking about this is like that first document, the thematic document where you had a note-taker sort of write down the differences between when you felt clarity and when you didn’t, like, everyone pass that around, take a photo of i t, that is how we came up with our manifesto. That second, the post-it note thing that we just did, take photos of that, too, because we hope that can be the basis of your plan for like, how might one go about like actually planning the documentation day? Where does it go? We did this activity when we started planning out how we would do documentation days and build that into our team culture. We have—did something similar and came up with a plan for like house this going to pan out? What is the process we’re going to use, and then continue to iterate on it. So I want everyone to take like the last few minutes here, if you have more questions or conversation, like we can do that, but take photos of the stuff, like write it down, tweet the photos if you feel comfortable sharing, because I’m going to be aggregating everything into a blog post, just about the ideas that came out of this, because we do it in a very set way, which actually during the session we published a blog post eh post on on exactly the process that we use on soliciting the ideas, deciding how to document, how we set up a Spotify for listening for all of the same music in different offices but I’m going to do a recap and Kelsey is going to do that with me of some of the best ideas because there are ways that we can also improve on this. So I hope there’s something actionable that you can actually take back with you. Any other comments, questions?

PARTICIPANT: All right, tweet on the SRCCON hashtag. Thank you … …