 Hi everyone. I'm a program manager at Microsoft working in developer relations for Azure. And I started working in tech about four and a half years ago. I taught myself how to code Python while I was commuting back and forth to my previous job by ferry in the San Francisco Bay Area. And there was one thing while I was teaching myself to code that I kept running into. And I still run into it now four and a half years later. And it's I miss scientific documentation. I just really miss it. And what is going on that that's the feeling that I keep having. Just three weeks ago I was teaching myself something new and same feeling popped back up all this time later. So the part that I haven't mentioned is what my previous career is. But by the title of the talk you're probably guessing something in science. I was a cancer researcher. I was trying to cure cancer. And we don't really talk about it that way when we're doing cancer research. But that's what I was doing. And I did that for about nine years. And no it wasn't data science. It was in the lab with the lab coat and goggles and gloves and pipettes and all the crazy stuff that goes along with it. And if you're wondering what that picture is it's a pretty cool picture. It's immune cells attacking cancer cells. And that's pretty close to what I was working on right before I left. But cancer research that's cool it doesn't really look like that day to day. It looks more like this. Scatter plots of cells. Those are each one of those little tiny dots is a cell. I'm analyzing them in what's called flow cytometry. And then taking a subset of the cells and analyzing them further. This is what cancer research looks like day to day. So why would I expect cancer research to be similar to tech? Like why? That seems pretty far apart. They're both part of STEM. But not the same right? Surprisingly though my transfer into tech has felt pretty natural. We both do split planning. The one on the left is literally an example of a split plan that I did. We didn't call it split planning. We just called it weekly planning sessions. We don't have cool names for stuff in cancer research. And on the right just an example from documentation of a split plan. So we both do split planning. We both do whiteboarding. I was shocked myself when I put these next to each other how similar they looked. One of those is actually the photo from my phone. Can you guys tell which one that is? The one on the right is mine. That's cancer research on the right. On the left. That whiteboarding image is from a Stack Overflow blog post. And also this. We both work on really complicated systems. And we both look into those systems when something goes wrong. Cancer is kind of the system going wrong. So that's all the same. Why? What is it that is still making me feel this way? That's all the same. We're all pretty logical. STEM. What's there that makes me feel like I miss scientific documentation just so much? Well, I think let's dive into what scientific documentation kind of looks like. Do you guys remember this? Scientific method maybe. Science. Chemistry. It's used across all of science. But I think the best way is for us to look even more specifically at the project that I was working on right before I left. And yeah, this again. This is bigger. I know. This is showing cancer signaling pathways related to a cell and how it evades the immune system. All of these things are going on. That's a lot going on. I worked on a couple of them. The stuff in the bottom left square, gray square. Some of that work that I did is published and now being used in people to not cure their cancer, but treat it. But with all of the stuff that we know, and let's just take a moment. Legacy systems, anyone? Legacy system. There's stuff we don't know. There's still questions. And that's what I was looking for. So in cancer research, I was looking for an unknown receptor that binds to a known protein that's upregulated in cancer research. So I was looking for one of these little question marks. I had to, when I started this project, I had to go and like, learn about everything that's already out there, research this space, decide on a plan to execute, execute that plan flawlessly, analyze output and kind of keep moving. That's the process. And I know some of you might be feeling this way, having these bad flashbacks, bio, bio class, biology, high school, college. I'm not sure. I know. I know. I promise you don't need to know any more biology to implement better scientific documentation. But the reality is that some of this process that I was going through that I just talked about that I would use to do the research, it should sound pretty similar to you all too. This is another thing that's similar. You have a problem statement. You break that problem into a bunch of smaller steps that might be easier to actually carry out. You go looking for tools, you go looking for a process that you think might be the right way. Then you actually execute that process. Then you confirm that the output is what you expected and you kind of start back over. You put the next little step or you maybe go to a whole new problem statement. Again, similar, bioscience. My problem statement determined a receptor for the Vista protein. That's kind of like saying an Airbnb competitor. I'm just going to build it. You're like, okay, but how are you going to build it? This is kind of some general ideas of how I would go about researching for this receptor. The first one is that I'm going to determine if this protein binds to certain cell types more than others. We know a little bit that this protein is in related to cancer immunology. We're probably going to start with immunology type of cells. Then the next step, I'm going to go start searching. That's what everybody does. We're going to go to Google. We're going to start searching. This feels really, really normal. We do that, too. There's whole analogous to Stack Overflow. There's two sites out there that are used for research a lot of times. The reality is that this is where things kind of get different. In science, we kind of do more of this. You might be like, what's a data? What? A data? What? You're thinking she's from Microsoft. You might be thinking this is not Excel. It's not a spreadsheet. I know you're thinking data. I showed you scatterplot. Nope. But it's not really prettier, either, because it's this. Yeah, that's what a data sheet looks like. Some of you who are in, I think, mechanical engineering was here earlier. Electrical engineering, this might feel pretty familiar to people like that. There's data sheets for little chips and stuff, too. But this is a protocol for how to separate immune cells from human blood. We're going to look at this a little bit further. But the key thing to keep in mind is just that a data sheet in bioscience is just like your vendor docs. In reality, there's two types of documentation that can happen in bioscience. There's your vendor docs or a data sheet, and then there's your laboratory notebook. And I can't really show you my lab notebook because that was a bunch of proprietary information, so I'm showing you mostly vendor docs. But everything that I go through is actually things I would do when I would write a protocol and put it in my laboratory notebook as well. So it all completely applies. So lab notebooks, self documentation, maybe that's like your runbooks or your code commits or your incident plan. Vendor docs is when you go, like you guys try to do, go and use someone's service. So back to our experiment. We need to isolate immune cells from human blood. And this is what those directions look like from that data sheet. That's a lot. But if I get rid of all the notes, that's what it looks like. So we're going to add something to a tube. We're going to dilute a sample. We're going to put the sample in the tube. We're going to spin it, which is centrifuging, pour stuff off, and then wash. Seems pretty simple. What if I added this? Yeah, there's an image. You're like, okay, now I kind of know what the tube looks like, kind of get how I'm supposed to be doing that. How many of you thought that you were going to come here today and learn how to get immune cells out of human blood? How many of you think that with these instructions, you could probably do this? Yes, yeah, see? Yes, this is what I'm getting at. Because great documentation gets you out of the how and to the why. Do you guys remember why we're doing this? We're looking for a new cancer treatment. That's important. That's a good problem that I want to solve. I don't have to think about, like, how do I actually have to do each one of these steps when I have good documentation? I can focus on the big problem that I'm trying to solve. And all of you are using documentation, do solve an unsolved problem, otherwise you wouldn't be looking at it. So what more, you just saw that, but what makes documentation more? I'm throwing in cool science images just because they're cool. That's a PC3 cell line that I used to use, and the blue is the nucleus of the cell stain. So one of the things that's missing, materials list, you guys might call it prerequisites. I started to see this in some documentation, but it's not very widespread yet. So what does that look like? This in science documentation, this is very specific. It's got an actual part number in there, gives you a note, actually, about that part number, all of it, very, very specific. Maybe this doesn't quite work in tech, but how about this? This is from the home project. They tell you you need to have a Kubernetes cluster because this project manages Kubernetes clusters and packages for it. It tells you here some other things you might have to have already decided or thinking about. So materials list. Let's do that. It's kind of like the homework. No one likes homework, but you know what? It helps you learn and it helps your users be really successful getting through the rest of your documentation. If you tell them what they need to go get, they're more likely to be able to get through it. I mean, if you were trying to cook something and there was no ingredient list, it would be kind of hard to get halfway through and find out, well, darn, I didn't know I needed garlic. It didn't say garlic anywhere up at the top. Don't make people go and figure out halfway through that they really should have had some login, some access maybe they don't have, some, you know, account they haven't signed up for. Make sure that they know what they need to do to be successful. Another thing, diagrams, pictures, who doesn't love pictures? Pictures are worth a thousand words. It doesn't have to be fancy like the one I showed before. It could just be something like this. It tells me kind of an overall process in a few lines. It tells me how long they take. So I know I used to run this. I really don't miss that six hour thing you thought compiling code and stuff was bad, but that's long. So in tech, what does it look like? It looks like this. This is from Hashicorp's terraform documentation. It's great. It tells me kind of where I am in the process, how long each one of those steps might take. So it doesn't take a lot. Adding a diagram doesn't take a lot of effort. And this might surprise you because of low vision type things, but it increases the accessibility of your documentation. There's a lot of us out there who are visual learners, myself included. There's people who have dyslexia or other reading is not their favorite thing to do. And then also, one thing that I think people don't think about is a diagram can help people when the language that your docs are written is not their first language or they're translating it. If you gave them a diagram, they're way more likely to have some kind of idea to piece it together with the bad Google translate that came through. This one, dates. This sounds really basic, but I don't know why every time I've talked to someone about dates on docs, it's like the most controversial thing in tech. Well, maybe not the most. But it's one of those things that people are like, no. Then people will know my docs are old. And I'm like, yeah, that's the point. Tell people. It's not bad. A book doesn't get less valuable. We still read stories from way back in the day, right? It doesn't make it necessarily completely unuseful. If it's older, it just gives me some context. Because this isn't every bioscience thing I've ever looked at. My personal lab notebook had to have dates on every single page. So let's add dates to this. This is not granular date. This is 2017. But having that information, I know this is a newer protocol than when I left. So I would know I need to go back and really reread this to make sure something hasn't changed. So I know it's newer. Works in reverse, too. It could be older. And then at least I know, like, okay, this still worked. Maybe some things have changed since then, but should still work. This was really hard to find an example for tech. I can't tell you. Some of you are probably like, wait, my docs are on GitHub, so it's fine. Sure. Still just put it in the top. Like, do not make your users go digging to see when the last commit was and whether you added a comma somewhere. That doesn't tell me that the docs are newer old. So put documentation where people can see it. It's just a hint for your users so that they know whether they're, like, experiencing something accurately or not. So if you go to somewhere and you see a different screenshot and you're like, okay, this button is not here, maybe it just got moved. If I know the documentation's old, it's really easy for me to be like, yeah, okay. They'd probably just change the UI. If I don't have a date, I might think that I've got somewhere I'm not supposed to be or I did something wrong or there's a problem in what I was doing. So just add dates. You already have this metadata. This is probably one of the easiest things for you to add to your documentation. Positive controls. Some people might know what negative controls are from way back again, chemistry or biology. So negative controls are when you don't expect an outcome. A positive control is when you are confirming that you've done something right. So you have a positive outcome and it's planned and you know that ahead of time. So in tech, this is kind of like confirmations and I'm sure a lot of you are like, I see confirmations all the time. Yeah, I don't see it in the documentation. Like the user interface has a confirmation but I'm not being shown that this is correct. So this is what a positive control kind of looks like for our cellular experiment. It tells me what a before picture of the analysis should look like and an after. So if I get anything besides just that one little clump down on the bottom in my after photo, I know I probably did something wrong. And if I get something that looks like that, I know I did it right. In tech, this might just be, this is taken from a tutorial on how to build a static website. And it shows you exactly what you're supposed to see as soon as you open up the browser if you get to this point. A lot of people have a lot of screenshots in their documentation. I think that's fine, don't remove those. But a lot of those screenshots don't actually tell you what you're gonna see after you click that button that you drew the red box around. It just shows me that I'm supposed to click the red button. So like tell people, even if it's a confirmation message, if it's a response code, tell people if there's like something from the fan line that it should have an output, give people that idea that they can see what they're supposed to have. Because it's kind of like a map and it tells you that you're heading the right direction. If you come out of a subway station and you're like, I don't know if 42nd Street is this way or this way, you walk over there and look at the street sign. If you don't have street signs, you're kind of like, I'm still not sure if I'm walking the right way. Positive controls are those street signs for your users. Don't make it so that it's hard to tell like, did I do this right? I'm not sure if I did this right. It also means that those are your checkpoints. So if you did do something wrong the next time, you don't have to go all the way back. You're not going to go all the way back to the beginning to try to figure it out. You're going to go back to that last checkpoint and say somewhere between my last positive control and this one, I messed something up. So that helps with your problem solving. Rational. So this seems like very basic, but put rationale why you would use something in your documentation. I know marketing might claim it does all these things, but like actually say what it does in your documentation and why you would use this one piece or this one feature. That shouldn't be too hard. But a lot of times we just dive right into like, here's how to like do this call. And I'm like, okay, do I want to use this API for this? I'm not sure. Bioscience. We have very, very long introductory paragraphs. It was this long. I'm not kidding in a page of the introduction. I took a couple pieces here just so you could read it, what it looks like. So it's telling me kind of about the biology that there's not very many immune cells of the type that I'm looking for in human blood. So it's a low number. But then at the very bottom in the blue, it says direct ex vivo detection and characterization of rare AG specific T cells. So what that's telling me is that I can directly analyze and work on these cells. And they're T cells. It's telling me that that's what I can do with it. So some rationale of like why I would want to use this. If I don't need to work on T cells, I probably don't need to use this protocol. So this is what it looks like in tech. This is from Honeycomb's documentation around how you would use or not heat maps. And I think it's great. It says like when you should not be using it, which is like don't use it if you're gonna get complete noise, but when you're gonna see a larger spread of values. That's really helpful, okay? I know when I should use something and when I shouldn't use something. So that's the lasting impact of your documentation is when you add that rationale and that use upfront. People don't need to remember to click that button. They can come back to your docs to do that. They need to know why they use the service or that feature in the first place or when they shouldn't. They'll be like wait was I supposed to, nope I wasn't supposed to use this one because this isn't the right thing. That rationale is the thing people remember. That's part of learning, is remembering the why. The how doesn't matter as much. So that's why I miss scientific documentation. And the thing to note here is that I showed you examples from tech documentation. You obviously have it, each one of these things and each one of your docs, there's some of it. But the difference is all those bioscience clips I showed you were from a single protocol, a single document that I went to go look at. And I couldn't find a single documentation site in tech. I've not come across one. If someone knows one, please come tell me. But I haven't found one that has all five of those things in a single place. It only has maybe one. Maybe you have a date, good job. Maybe you have positive controls, well that's very rare but good job if you do. But no one has put all of these things together even though to me this is just standard. This is like everything. Even my lab notebook had all five of these things for every single experiment that I ran. So let's shift from focusing on the how we do things to what problem that we're solving. Let's get our documentation to the point that people can really focus on that problem that they're working on. Don't make it that difficult for your users. And apply this also to the stuff that you develop internally. Those five things that can make a big difference but you need them all together. One of those isn't gonna make great documentation. You need everything to kind of come together. But as you saw, they're actually not that hard to implement. They're pretty small, it's not more docs, it's just a few little bits that are missing a couple of holes. So I hope that this science did not bore you too much. One more scientific photo for you all, 3D cell culture with some S-I-R-N-A in there. And our tech slides are way cooler than our bioscience slides. I will definitely give you that. We do not have GIFs. We have lots of the scatter plot graphs and the cell diagrams and stuff. But one thing that I do feel like scientists did do that was cool in their presentations is we always had an acknowledgement side, which is for anybody who helped you do your research, or supported the researcher. So I just thought I would add that as well. Major shout out to a couple of these people who helped me.