Technical Writing

[00:00:00]
>> That's where we are. And now we are gonna hop into section five, technical writing. This first bit here is just we had a bunch of stuff on communication. How does that apply to specifically technical writing? Everything I told you before generally applies to meetings, public speaking, writing emails, writing memos, writing slide decks.

[00:00:24]
Here I'm going to be focused on the act of actually mostly just writing docs, but this could apply to slide decks as well. And I say that as well because when I was at Microsoft, everything, everything was a slide deck. We didn't write very many Word docs. We generally, even when we weren't gonna present it to anybody, we wrote it in a slide deck and sent it to them.

[00:00:46]
That was just the culture. And then I got to Stripe, and Stripe almost has a rule against slide decks. So everything was a doc, we would get into meetings and we would look at docs together. I mean they're both extremes, that spectrum. I think I prefer the docs personally because I was really good at going through, I actually bought an iPad just so I could sit on my couch and read docs, there's so many docs to read.

[00:01:10]
I got a lot of context really quickly with that. But from a visual perspective, it's lacking, right? Because putting things into a slide deck gets people in a visual mindset and this will put like a lot of visual aids in there, which I think is helpful. So, I don't know, it's a trade-off.

[00:01:27]
Both of them have their downfalls. Snowflake is a good mix of both. So I think that actually works out fairly well
>> Do you have an opinion about [CROSSTALK] well, scope it out [LAUGH] And if you're Edward Tufte, this one's easy. But is there a format that you prefer or you'd recommend, culturally there's preferred formats, but long forms are not going to go into slides very well.

[00:01:53]
And documents are not going to encourage terseness. Do you did you have a set of practices to help yourself you know, keep the format from infringing the information that you wanted to communicate?
>> Yeah, it's a good question. I mean, my high-level principle, is I just want to get stuff done.

[00:02:13]
I'm really excited to build things, and I'm really not excited to spend time arguing about things that I think I'm right on. Particularly with, if I feel like I'm going to something that I'm not going to learn something, I kind of go in there like a bull and just say, either we're going to do this or I'm going to go around you, right?

[00:02:29]
[LAUGH] So given that, I generally cater strongly to the audience that I'm going to be speaking to. And so, executives do really well with slide decks, right? Architects love documents. And so I kind of try to cater my communication to the audience. It's just kind of like I'm very much a pragmatist in the sense of, I don't care how I get it done, but I'm just going to get it done because I'm really excited to get it done.

[00:02:58]
If you'd asked me like just purely on preference, I like writing docs, I think I'm better at it. I think I write better, and I still use a lot of visuals on my doc. So I'll actually have sections on diagramming here of how I think you can make your docs more appealing to a visual crowd.

[00:03:14]
I think that is probably the best way to do it. I love the format of having a one-pager proposal for something, having maybe a six-pager ish product spec, and then if you need something having a 15, 20 pager technical analysis, architecting kind of doc, right? And that kind of minimum context, medium context, massive context.

[00:03:39]
I think that kind of information hierarchy works really well. If I was running a company, that's generally how I would do it. Whoever proposes it writes the one-pager. Whoever PMs it writes the 6 pager and whoever architects writes the 20-pager. And sometimes in there, if gathering a company around a slide deck makes sense, I will use that tool when I need it.

[00:04:05]
But you have to kind of think of these docs not in terms of just when I'm going to be presenting to it, but it's actually your ability to influence people when you're not there. So if you write a really good doc and it gets sent on to someone that you don't know, that's you extending your influence beyond just your immediate ring of influence.

[00:04:21]
That artifact carries power beyond you. Now some of you are at startups and beyond you is literally the person next to you. But me at Microsoft, I found out people in totally disparate parts of the organization were reading my docs and they were basing their own processes on stuff that I had written.

[00:04:39]
I had no idea. Right? And so I was able to have influence without even cognition, right, that's real power, almost, no, I'm just kidding [LAUGH]. But it is, it's cool to have that kind of influence. Okay I will say that I don't actually, as much as I'm talking about writing, as much as I think about writing, I actually don't really like it.

[00:05:03]
It's not like I'm pumped to get up and I'm like, I'm gonna get into Google Docs today. I do not do that, right? And sometimes I even dread it sometimes, right? But I do recognize that it is my lever for influence. So, I'm just gonna throw that out there.

[00:05:19]
If you feel the same way, I'm just validating that like it can be okay to feel a little bit of dread at like, I'm going to have to write another long doc today. But yeah, it is. It's by far your way to be most effective. And like I'm saying, this is a PMing course, but if you're in QA, if you are in production, if you are in Customer Service, if you're in customer service and like a bug keeps happening to all of your customers, write a doc about it and send it to the engineering org, right?

[00:05:49]
That's, your ability to change how stuff happens over there, right? It's not enough to just talk about, it's not enough to complain about it. Having it written down allows it to be shared and shared again. Cool. So, who is reading your email, memo, slide deck? Think about it.

[00:06:14]
Sometimes even write it. And this actually has been really useful for me. I wrote a really long strategy doc. I was really proud of it and I was writing it for internal people that were already bought into my vision. And when I went to my boss and we talked about it, this was several companies ago, they were, why did you write this?

[00:06:37]
Like none of this makes any sense to like the CEO and stuff like that, I was like, that's because I wasn't writing it for them. Like I was writing this for internal stakeholders, and like having that discussion really quickly realized that like, we had way different ideas of what this doc was for.

[00:06:50]
And the answer is we were both right. Both of those docs were super necessary. But those mismatched expectations meant that, the wrong doc got written whenever we thought the other doc was gonna get written. So the end result is that we ended up writing another doc and then we had two docs, right?

[00:07:05]
So getting that right, making sure that you are matching your audience, critical. Yeah. You write differently for internal stakeholders versus external stakeholders. I haven't said this anywhere in here, but like be really careful around initialisms, acronyms, code names. If you don't think it's going to be obvious to everybody writing that doc, don't use it, just spell it out.

[00:07:36]
One thing that Stripe did that actually was every company has like, we have an acronym database where you can look up anything, and it's never up to date, except Stripe's. Stripe did a really good job of keeping all of theirs up to date, but it was so old and so long that every initialism had at least four or five entries for as like, here's what CTA means, and there was like nine entries.

[00:07:58]
So good luck figuring it out. In other words, you are driving understanding, you are optimizing for the understanding of readers, not for how fast you can write the doc. So always optimize for the reader. And I'm giving you a bunch of things here. Some docs are just written to be shared quickly, right?

[00:08:22]
Like if you're taking minutes from a meeting, don't overthink it and turn it into this wonderful bit of prose. Write quickly. Some of those actually are optimized to be written quickly, and are just, reminders of what stuff that happens. Or, if you're like writing like a half-page email to that's just going to one of your colleagues, write it fast, right?

[00:08:44]
Value your time with their time in those particular cases. So make sure you're focusing on a reader, therefore you don't underwrite and therefore you don't overwrite, you want to be right there in that sweet spot in the middle. And like we're going to like we're getting back in here to the say less, but let me just assure you that zero percent of readers read every word in your doc or your email, or your slide deck.

[00:09:13]
0%. No one reads every word. Everybody skims. Really interested people like will pause frequently on what they're skimming for, but they're still skimming, and uninterested people might open the doc and then close it again. Right? Nobody reads your entire doc. I venture to say you are not going to read your entire doc later, right?

[00:09:35]
So ruthlessly cut unnecessary stuff from your doc because you run the risks then of people skimming over the stuff that you actually want them to read. I'll talk about how to anchor your doc in different ways to get people to read the parts that you want them to read, but just recognize, you're basically in a race against the clock.

[00:09:54]
And the clock is their attention span, right? So make sure you are saying the correct things and you're cutting out anything that doesn't need to be read. Sometimes you have 15 seconds to talk to your reader, sometimes you have five minutes, extremely rarely do you have more than five minutes to talk to your, whoever's reading your particular doc.

[00:10:15]
So, optimize for that. Yeah. Rarely will it take more than five minutes. One to two minutes is a pretty engaged reader. And, like, 30 seconds to a minute is probably your average reader. They're going to skim. They're going to look for stuff that's interesting to them. They'll read blurbs here and there.

[00:10:34]
And then they are done. And reading another doc, to reading another doc right? So respect their time. Every place I've gone I've had a couple of like really trusted PMs that I work with or engineering managers or engineers or whatever, and I've written some important doc, very quickly I'll just send them like, and I'll ask specifically is like, am I capturing what we're working on here?

[00:10:59]
And I'll usually get pretty quick feedback of like, do you agree with the content? Do you agree with how this is formatted? Does this communicate pretty well? And when you find those people that are like, you both value what they think, and they will give you ruthless feedback, worth their weight in gold, right?

[00:11:16]
Like I was, I was talking about Maggie earlier. That's literally why I took Maggie from Microsoft to Stripe with me, because she's phenomenal at that. She's probably one of the, she's probably the best person at that that I know. And I tried to take her to Snowflake, didn't work.

[00:11:30]
[LAUGH] So finding someone like that, some sort of trusted partner for me, at Snowflake now it's my engineering manager. I send everything to him quickly, he once-overs it, my boss is really awesome at it too. And getting some quick feedback on that. Having a culture of commenting on docs is helpful as well.

[00:11:55]
So like Snowflake is really good about this. Everyone will just highlight something, leave a comment in it. And then there's always an appendix at the bottom of every Snowflake doc of just long-form comments from people. That was new to me and I actually quite liked that. So in order to get that kind of feedback from other people and get useful feedback and thoughtful feedback from people, you need to be a useful partner for them.

[00:12:19]
So, that's sort of some sort of reciprocation there so getting some sort of eye for it. And really that really involves moving beyond yourself and not saying things just to say things because we all know people that say things just to hear the sound of their own voice.

[00:12:34]
But actually trying to give them concrete steps to accomplishing their goals, that's the mark of a good editor or a good comment or feedback provider. So those two things I think will yield good feedback quickly.