Diagrams

[00:00:00]
>> Let's talk about diagrams. I think that's an underutilized part of being a PM is doing visualizations, and it's something I've kind of learned over my career. I'm not an artistic person, I don't like drawing, I don't like any of those kind of things. So I generally default to a state of not wanting to go do additional work to say the same thing using a picture, and you absolutely should because it's really easy to say some things with a picture.

[00:00:26]
This is actually a real diagram that I made at one of the companies I worked at. We had a proposal to submit, to ship three different SDKs, one that was only old features, one that was only new features, and then one that was a bridge between two of them.

[00:00:47]
We had some users that we knew only ever wanted to stay on the old stuff. We had new people coming in, and we knew that they were only gonna wanna use new stuff. And then we had people that were on old stuff and that would want to get on new stuff, that's really hard to say in words, right?

[00:01:05]
So I was trying to communicate here if like we have v1 APIs, we have v2 APIs, they are incompatible with each other. So we're gonna have to write a little interrupt layer between making v1 stuff and v2 stuff work together. And when I was trying to explain this to people over and over again, they're like too many words Brian, we don't get it, right?

[00:01:26]
So I did this diagram okay, over time this is how it's gonna look. So GA stands for general availability, or it means when you release something publicly forever. So I was trying to diagram snapshots of time this is what it's eventually gonna look like, eventually sdk and sdk-next are gonna be the same thing.

[00:01:45]
And eventually when that happens then we drop sdk-next because sdk is just now all of sdk-next, and then once we start deprecating old stuff or like removing it, the sdk-classic is going to shrink over time until eventually it's gone. And the only thing left after five years of a migration will be just sdk.

[00:02:05]
We didn't end up doing this because as you might imagine, that's really complicated. But they gave me a bunch of product requirements, that was the only way I could accomplish it. This was a useful tool for me to go back to I was like, this is what you're telling me to do.

[00:02:16]
And I can do it, but it's weird and no one else does it this way, right? And then eventually they came back and said, maybe we shouldn't do that way, I was maybe we shouldn't do it that way, right? So this was actually a really useful lever for me to go back and say, here's what you're actually telling me, this is the fundamental impact of your constraints.

[00:02:35]
And they're like, our constraints are dumb, and I was like your constraints are dumb, right? It was a very useful tool of communication. But it's just boxes, right? I guarantee you these are not spaced correctly. I guarantee you that these are not, like you can see I have the line in the middle of the words, that looks really dumb, right?

[00:02:57]
But my point was communicated and it was communicated effectively. My point here is that, these don't have to be pretty, right? These don't have to be right, you should do these fast, and you should only put as much effort into it as it makes it clear for communication and put zero more effort into this.

[00:03:12]
You should remove all of the concepts of I need to open sketch, and I need to go get the designers. Sometimes you need to do that, if you're trying to make a proposal for I don't know something where that would require that level of polish. This was just wanting to one of my throwaway doctrines like all right, I'm gonna throw something weird in the page and see what happens, right?

[00:03:32]
Make sure you put in the appropriate level in here, and please remove all the expectations of everything needs to be pretty. Most things don't need to be pretty. Particularly if you're not a designer, which as you can see here I am not, I am not a designer. So this is all done in Google Drawing, that is typically my weapon of choice, that's just the one that I know.

[00:03:55]
It's very simple it is, I like that it's very simple because it forces me to not do very much because you cannot do very much, right? And same things you can go to drawing.new and it opens you a new Google Drawing right away, that's very helpful for me that I can just do it at the drop of a hat.

[00:04:14]
A lot of my colleagues, particularly at Snowflake like Excalidraw. Same thing, more powerful, free and online. I think there is some paid tier to it, I don't know what it is, I don't pay for it, so I don't know. If I need something with a bit more fidelity, and I say a bit more fidelity, a couple of times I've reached for Excalidraw.

[00:04:35]
I see people do it in Google Slides and PowerPoint quite frequently. It's really easy to just like diagram something out and then just take a screenshot of it, or export it as a PDF, or an image or something like that. That's very effective if you find that you're really good with those tools.

[00:04:51]
Figma, Balsamiq, Canva, Sketch, Photoshop, InDesign, by all means if that's something that you are good at and wanna use, do it. I don't because as soon as I have all of the tools available to me, I get really tempted to make it pretty, and that I spend a bunch of time making it pretty, which does not help my doc.

[00:05:12]
It's just self aggrandizing of look how pretty my diagram is, and nobody cares. Especially me, I don't care. So, do it if you have restraint, I do not have restraint, so therefore I don't do it. I've seen people use Visio or Lucidchart if you're really good at UML diagrams, which if you're very good at UML diagrams, I'm sorry for who hurt you.

[00:05:38]
[LAUGH] That's not some thing I have done in years and I do not plan to. Sometimes it's used for the show like flows, in those cases actually it's extremely useful, but beyond that particular use case I don't use them very much. Questions, concerns here? Yeah.
>> Do you have a metric or a way of deciding what's an outer limit for time spent on graphics, and part of the motivating question is you're tooling.

[00:06:13]
I found out about mermaid JS like a couple years ago, and suddenly I have a lot more time to make complex diagrams, because it doesn't take me as much time. And I had to kinda rethink my workflow on that, but when you're working on a document and you're trying to get it done, where is your boundary?

[00:06:29]
Or where do you draw the line to say, I'm putting too much time in for the return I'm getting?
>> It's always impact versus effort here, right? If more time leads to much more impact, I'll spend all day, right? If I need a really well crafted diagram to communicate something to a lot of people and that accomplishes that goal, and less time on it doesn't do that, that is the calculations I'm doing.

[00:06:53]
I don't have a hard limit, I have a what am I getting from more time spent on this. I could have spent tons of time making this probably 5% clearer and much prettier. I didn't do that, this took me all of probably 15 minutes to draw, right? The only reason that I have this from my old company is I forgot to do it in my company account, so it's on my personal account, right?

[00:07:16]
[LAUGH] And so that should tell you how fast I was going there. I was like, I don't care, I'm just doing this as fast as I possibly can. So typically I can knock these out, particularly with Google Drawing cuz I've gotten somewhat adept at it, ten to 20 minutes.

[00:07:30]
And if I'm gonna spend any longer on it, I need to justify to myself that this is gonna have a larger impact, yeah?
>> One additional tool suggested by the chat is eraser.io, which claims to be the whiteboard for engineering teams.
>> Eraser.io.
>> Eraser.io.
>> Not what I'm familiar with, but very cool looking.

[00:07:56]
I think if I was gonna do some sort of, this is obviously an architectural diagram. When I start getting out to like zoomed out to like this, I usually hop to Figma because that's the one that I have enough familiarity with to work with. If you're gonna learn something like this and you don't already know, if you're on Eraser and you like it, by all means stick with it.

[00:08:17]
Figma is a extremely cool tool and can do a lot of things. So if there's one to spend time on, that is a very useful tool to have in your tool belt.
>> Brian, do you find value in inserting maybe a working session whiteboard, pretend we were all in person, and noodling out ideas and visualizing it into your documents?

[00:08:41]
Or would you take those whiteboards, put them into something like eraser.io or Miro and then put it in your doc?
>> I've done that for brainstorming sessions. I found that to be really useful for like a remote team of like, all right, everyone stick your sticky notes on the board.

[00:08:56]
That's been with Figma just because usually it was a designer running the session, and designers live and breathe Figma.
>> Yeah.
>> I could see it definitely being useful, it's just not something I've tried too much.
>> Okay.
>> Yeah, so I don't have a good answer for you.

[00:09:15]
But visual representations, and I found a lot of value to just take an engineer into a conference room and just diagram stuff on a whiteboard. That's always been so useful, so I see any extension of that being useful.