Celeste Horgan
Rich: Hello and welcome to Kube Cuddle, a podcast about Kubernetes and the people who build and use it. I'm your host Rich Burroughs. Today I'm speaking with Celeste Horgan. Celeste is formerly of the CNCF and uh, going to be landing at some point at a place that's a mystery right now. Hello Celeste.
Celeste: Hello. Yeah, recently of the CNCF a few weeks ago, depending on when the recording goes out uh, and in a few weeks landing somewhere else, depending when the recording goes out.
Rich: I just saw the announcement the other day on Twitter, that, that you were letting folks know that you're leaving. Uh, I usually start out by talking with people about their journey into computing. I'm wondering like what it is that draw you into, drew you into this world.
Celeste: It was a bit of a multi-step process. So my parents got a computer when I was about 11 or 12. And pretty immediately I became fascinated with the idea of building your own website or having your own website. And it was something that I asked my parents for in, for Christmas. When I think I was again, 11 or 12, I was like, I would like my own website.
So they signed me up for a Tripod account. And I, my first website, my first I had a few like smaller websites as I was like learning HTML and stuff by like copying pasting from other girl's websites. And it was very much like young girls. But my first real website was a Sailor Moon website. And I just sort of kept like animating game websites up pretty much through high school.
Um, got into to university. All of my teachers said that I was a great writer and that I should go into UVC English. I live in Vancouver, BC right now. Um, my teachers in school were like, no, but you should absolutely go into English. You're going to love it. And UVC English is the best.
And it is a very good English department and I was totally miserable. Yeah, completely miserable. And I was also for lack of a better word, a little too smart to do an English degree and not realize that there's not much at the end of that degree, in terms of like really set career paths. And I came from a poor background.
I had student loans, I was like this, I got to cut this off immediately. Cause I'm going to get four years in. I'm going to have a ton of debt. I'm going to have no future. So I did some computer science classes at UVC my first year excelled in that. Um, But I didn't want to take the math courses.
So I ended up going into an interaction design degree at a different university, Simon Fraser University. And that's where I really got into tech. My first job in tech was as a co-op at Blackberry as a technical writer. And that's where I picked up technical writing. Did a bit of UX design ended up going back into the technical writing.
I always wanted to work in open source. I always thought it was just like this really cool philosophical thing. I thought it was just like awesome that people were doing this just cause they wanted to. And I always thought it was really exciting. So when the opportunity came up at CNCF, I was like, yeah, let's go.
And the rest is history as they say,
Rich: And how long were you there at CNCF?
Celeste: Two years. So I started as a contractor in January, 2020. Eventually went full-time January, 2022 was my last month.
Rich: Awesome. I'm so glad that we're able to have you on the show. I have not had a technical writer as a guest yet up to this point. I've been very aware of you and your work. I've seen a few of your talks and I think you're fabulous. So, uh, I'm really interested in digging into this topic.
And um, I think I mentioned to you before we started recording that I usually put out this call for listener questions, like maybe a few days before the recording session. And I got so many questions for you. Like even more than, you know, much more than I normally do. So it's a topic that I think other people are interested in as well.
So I'm super excited to get into it with you. So, uh, One of your talks that I've seen that I really enjoyed was the one um, from KubeCon called Writing for Developers: Take your Project to the Next Level. And there's sort of a quote in there that I really loved. You said that the work that gets done is what the community chooses to contribute to, when it comes to open source.
Celeste: And that was, so I hadn't worked in open source prior to the job at the CNCF. So I very much jumped straight into the mouth of the volcano on this one. I think most people tend to tiptoe their way in. And that I think was the biggest mentality shift for me. When you're working in documentation at a product company, The work that gets done is you document every single feature.
There's just no question about it after a certain point in time, it's less about adding features and it's more about maintaining the documentation set and making sure that things remain accurate. It's a slightly different thing. But I think that's super important to keep in mind when it comes to open source.
Because I think even if you look at it from a corporate open source perspective, like these large companies like Microsoft or VMware there is a propensity to staff projects with developers. And so the work that gets done by developers is development, but that's not what makes a product. And Kubernetes is a product.
And I think any large successful open source project, even if it's a third of the scale of Kubernetes. It's a product, you need to treat it like a product. So if you, aren't going to staff, people who do things like writing, who do things like community management, who do things like program or product management, you are going to have some massive deficits in your open source product.
And it's not going to be a success that as successful as it could be.
Rich: Sure. Yeah, absolutely. Yeah. It's interesting too, because I think I'll um, some folks who do work on upstream Kubernetes as part of their jobs they aren't even full time dedicated to that. Right. That might just be like a slice of what they do in the week.
Celeste: Yeah. And I think that's maybe, at least from my perspective, after a couple of years in the CNCF, which is a very different perspective than many people in the community, is, again, like get staffed, determines what gets done. And it's, I think that's a mentality shift that needs to start happening in open-source communities where it's far more relevant now than it was 10 years ago.
It's far more critical now than it is 10 years ago. And I think the age of unevenly staffing projects, or I have a bit of time off the side of my desk to work on Kubernetes. And then my real job is something else because my company doesn't understand. I think that age is rapidly going to come to a close because I think it has to come to a close.
So my
Rich: Yeah, no it's a really interesting point. And when you think of especially companies like the cloud providers, who are providing managed Kubernetes offerings, it's definitely in their best interest, right? For the users to have good documentation to fall back on.
Celeste: Well, Yeah, when their when their SREs running their clouds have a problem, who's going to solve them for them?
Rich: True that as well. Um, So like I said, I re I really enjoyed that talk and in that talk, you used the Hero's Journey as a metaphor for users and how they kind of encounter documentation. And it's a concept that I'm familiar with. I was a Theater major. And I've learned about Joseph Campbell and all of those things at some point.
But for those who maybe aren't familiar with the hero's journey, like one example of that, a lot of people will probably connect with is Luke Skywalker. Because George Lucas, in, when he was constructing that for Star Wars film specifically was using the Hero's Journey. It really, his character really maps well to that, the idea that you've got this person who's just starting out and then they gain experience.
And, in the end they're able to overcome the big challenge in front of them.
Celeste: I, the large part of my trade is communicating information and I think that talks are a slightly different format of communication then documentation is. I could very easily point you to the contents of that talk in like a blog post or like a technical writing 101 course. But I think when you're giving a talk, you have to give people a story to latch on to that has a clear beginning, middle and end.
So I'll be perfectly honest. I sorta felt like I shoe hammered like the metaphor a little bit for the times, but I was determined give it a kind of narrative structure because I think that's what talks are compared to documentation, which is reference material.
Rich: I didn't feel that way
Celeste: Oh,
Rich: were hammering me over the head or any big. Um, but, But you mentioned this idea of, the user coming to the documentation with a goal of something.
Celeste: So I am one of the questions that came up in your tweet thread was like how to developers get better at writing documentation. And I think the thing that I see the most often with developers when I talk to them. So like the it's a little different than open source, but the typical way a technical writer works with developers is you make a thing.
I sit you down in a room and I say, explain the thing to me. And we go from there. And the thing that I find most in those conversations with developers is they start at like the implementation of it. They're like, okay let me tell you about this base 32 encryption. I'm like, I don't think your user really cares.
Like I don't really think they care about the encoding of the database, unless it's like actually important cause they might screw it up. Um, and I think that's the piece of advice I usually give people the most, is, you need to think about it from their perspective. And most of you are developers.
You already know how you use the documentation because you do, which is you're trying to do something because somebody given you a ticket. And if you're, let's say you're a junior to intermediate, maybe even a senior developer, somebody's giving you a ticket, you're trying to do something very specific as described by the ticket.
You have a bit of the thing memorized, but at some point you hit a thing where you're like, oh man, I have no idea how to do this. I have no idea. So you go to Google. Um, you Google, how do I do blank in Go, or Java or JavaScript or whatever you're working in. Right. Uh, So you already come in with a goal in mind.
And what you hit off of that Google search may not be the exact answer. So you gotta do some digging, right.
Um, so that's one example of a goal is, I have a specific thing that I'm trying to accomplish. Another example of a common goal is, you are a senior plus engineer. So senior, staff, principal, you're an architect.
Somebody asking your opinions. We are doing insert blue sky thing here. Brand new shiny object here. What should be used to do it? And it's your job then to look at all the options for your thing, for your logger, for your container runtime, whatever. Read the documentation, to understand its features and evaluate it against your needs.
And I think as soon as you start thinking about document, those are the two big ones. In my opinion, once you start thinking about documentation in those terms, it becomes very easy to understand what you need to write. How do I help the person do a specific thing. And really then it becomes a matter of tuning, what is the specific thing? Am I being too specific or am I not being specific enough? What information does the person need to know to do this specific thing? For example, if they're doing a containers thing, or if they're doing a Kubernetes thing, they need to know what a container is, probably. They probably need to know what a pod is.
They need to understand this concept of orchestrating pods and why you might want to do that. So you're going to need to write that down at some point, so that they have the requisite background information, and then they can do the thing. Then you explain how to do the thing for them. Um, and again, like some of the documentation overlaps that second major use case of, I need to understand if this thing can do what I need it to do. And you do that by explaining here's all the things that it can do. And you it's a mentality shift, but I think that we actually, sorry, I'm rambling, but
under serve our junior developers in some ways, because they were in that funnel of somebody gives me a ticket, I implement the ticket, I get the next ticket. They aren't necessarily encouraged to think about why or how that functionality fits into the overall product, how that affects the user, how their decisions and implementation affect how a user can use something. And so again, you talk to them, and I've talked to developers who have no idea how their things are being used.
And that's why you should hire technical writers.
Rich: That's, super interesting. And I feel like these topics overlap a lot. Like you mentioned your background in UX, that UX, product management, all of these things apply here in the talk that you mentioned. And I think we covered this, but you mentioned concept docs which sounded more like the docs for that person who's doing the evaluation or doing the POC.
What do you think makes a good concept, doc?
Celeste: It depends.
Um, the thing with concept docs is they, everybody needs to review them at some point. It just depends what your style is. There a really interesting academic study that I read once that studied how developers consume API documentation. And they showed it was actually about 50/50. 50% of developers were looking for these specific fields they had to send to an API, they were looking for code samples. They just wanted to copy and paste something. And if they didn't understand it based on the code samples, then they would go and read the conceptual documentation. The other 50% started with the conceptual documentation. They read all of the conceptual documentation and then they decided what they needed to do.
And then they looked at the code sample. So I forget what your question was.
Rich: My question was what makes a good concept, doc?
Celeste: Okay.
There we go. Sorry this is the ADHD kicking in. We're at the end of the day,, which means at the end of my pill,
Rich: Yeah
Celeste: Um, what makes a good concept doc? It, again, it depends on what the piece of software is. Really one of my favorite examples out there in the wild is actually Honeycomb's documentation, for concept docs. Because Honeycomb had to introduce not only the product and how to use it, but the paradigm of observability. They were introducing a new concept completely.
So they had to explain what that concept was, explain the important sub concepts that someone needed to know. And then they had to compare and contrast it to technologies that people already knew so that they could understand the connection and understand why it was important to use an observability tool.
So I think it really depends on whether you're introducing an entirely new concept to your people or not or whether you're leveraging concepts that exist elsewhere. The other example of concept docs that I've written, I've done a lot of work in e-commerce in the past. And while those terms may be new to the developer, like for example, PCI compliance. It is broadly speaking a concept that exists out in the world outside of software development.
So it's about briefly introducing it to them and then saying, if you want to know more click on this link and then diving them into something more technical that they're more interested in. Aside from that it's "blank is a blank that does blank." That's all you need to know.
Rich: You brought up a really good example in your talk, you mentioned the Vitesse docs that like literally started out with that.
Celeste: Oh yeah, that's it. That's 90% of it. If you can boil down your concept to "blank is a blank that blanks," everything else is just icing on the cake at that point. And if you can't boil it down to that, there's, there's other issues at play for you that you might need to work through with your product?
Rich: Yeah. What about the reference docs? Are there any specific challenges with those like API documentation, things like that?
I know a lot of folks nowadays are just generating those automatically. They're not necessarily writing them.
Celeste: The real, I mean, there's all, there's all sorts of issues if you really want to get into it. Um, I kind of love working on reference documentation because I have a UX background and I think the thing that's interesting about reference documentation is there they're working manuals. They're designed to be the thing that you would keep on your desk and reference over and over again, as you're working on something. They're not meant to be something that you read once and put away. Um, so the key there is keeping them informative enough for a newbie, but also keeping them like succinct enough for the person who has to look at this a hundred times a day. Um, and I think in terms of like actually presenting that documentation, there are usability heuristics there as well, which are really interesting.
Um, like don't think I ever worked on an API where anybody has ever solved the API reference documentation usability problem. Um, I mean, I guess I'll just let the cat out of the bag. Uh, so I'm going to Stripe, uh, in a few weeks, uh, as a staff technical co-writer along with a bunch of other really talented writers.
Rich: Which, from my perspective, they are known for
Celeste: They, they are, they are known for having. fantastic API documentation. Um, they've come the closest that I know of, it's them and for a period of time Twilio, but I haven't checked in on Twilio's docs in awhile. Um, but it's interesting because in my interview loop they brought up the docs. They're like, what do you think is going well? What do you think is going poorly? And one of the things I brought up is in the years, intervening, since Stripe went through a big docs redesign and did a really fantastic job like five or six years ago um, they've introduced a lot of nested data structures into their API, which is very common for any kind of payments or e-commerce company.
And that was one of the things I brought up is like, this worked really well when your API didn't have these nested JSON data structures. And now that it does things get a little weird in terms of the UX of, of scrolling through, um, page. It's also just a bigger API now and you know, that sort of infinite scroll silo page, um, hits a limit of usability at some point. Another example is for example uh, like help menus in command line tools, um, cause that's referenced documentation. And there's a usability thing there too, that is often maintained in the source code for the CLI tool. Um, and developers don't think about naming things in particularly friendly way sometimes.
Um, the order that things are supposed to be put in, like the order of flags and commands, um, Git recently changed theirs, actually like in a recent version uh, and I had to like relearn how to push things to a fork. Cause they like change the order that they wanted one of the two words in and just, nobody thought about it as like a UX problem.
Rich: Wow. Yeah. It's, it's interesting. I wouldn't have thought of those kind of command line help things as being reference docs, but it totally makes sense. Um, I've also seen situations where the stuff that's in there, you know, that you get from the actual CLI doesn't match up with what's in the documentation that's on the website or whatever.
Celeste: Yeah. Uh, I mean, and that's, that's where you sort of start to see the cracks in an organization form, right? It's it's usually an issue of siloing. Um, where like the people either know that writers exist. They don't know how to talk to writers. They forget uh, whatever.
Um, And that's usually where product management can be a really helpful friend. Which is like, if you can manage to get product management for an open source project to sort of say, to finish off your coding task, you must make sure the documentation situation is taken care of. Either somebody else's writing it or you're, you're writing it or you're reviewing it. Then you're usually in a better situation.
Rich: That totally makes sense. Um, so you have been involved with the Kubernetes docs specifically, I think like, were you on a SIG or a working group or...
Celeste: I am on SIG docs. Um, I am also on the Kubernetes Code of Conduct Committee. Um, I started and ended the Naming Working Group for Kubernetes, I uh, over the course of a year with Stephen Augustus. Um, and in my role at CNCF, um, I was kind of. I, I looked at all the docs, not all the docs, but a lot
Rich: Yeah.
Celeste: for a lot of different
projects, so,
Rich: So with the Kubernetes docs specifically, um, I wonder like what, what you saw in your time, like working on those in those couple of years, like what, what's it been like? The, because there's been a lot of growth. There's been new features getting added. Um, how, how are the docs do you
Celeste: think?
Ooh, that's a question. And I say that with like the utmost amount of love. Um, let me answer in the more general sense of like, and I'm hoping to give a talk at this at the next KubeCon, so hopefully it gets accepted, but like there's the interesting thing about working at the CNCF is you actually get to see projects in different stages of maturity and you get to see the commonalities between the different stages of maturity.
So. Kubernetes is a very mature project at this point. Um, and from a documentation set, it is pretty much at all times feature complete for all intents and purposes. Um, and so it has mature documentation set problems. Um, at some point some interesting, uh, decisions were made with the information architecture, uh, or how, how the documentation is organized. And, um, typically in a product company, um, every few years, you, you kind of tear things down and you put them back together again. Um, documentation is a garden which must be weeded. It's not, it's not a statue that's built. It's just, it's a, it's a process of weeding at all times.
Rich: We did some weeding recently where I work. I totally know what you're talking
Celeste: I mean, we're doing some re weeding right now uh, with removing Docker shim, um, and. That's something that I think the current documentation set really struggles with is they're, doing large scale work when you're in a private company, working on a product is not, it's disruptive, but it's possible. Doing that kind of large scale work in an open source project would be the, you know, functional equivalent of like rearchitecting a large part of Kubernetes. Like highly disruptive, highly divisive. Divisive to the point where it can't get done. And that's where the documentation is right now, where some interesting information architecture choices were made a few years back and they have continued. And normally you would say, Hey, we gotta reorganize this. Um, but it's hard to do
Rich: No, that totally makes sense. Right? Because normally, if you were doing that in a product company, like you said, you know, there would be business stakeholders that you would want to get on board with the fact that we're going to make this effort and it's going to take so much time and, and, and there's not really that kind of stakeholder necessarily for Kubernetes.
Celeste: Yeah there is and there's, it's a matter of not having those stakeholders and also having too many stakeholders. And I say this with the caveat of like, I'm not in SIG Docs leadership right now. Um, and I, they've recently, um, elected new leads, uh, who are awesome. Um, and I'm not trying to criticize anybody's work here. I'm just pointing out a problem that I see from my perspective. Um, so, with Kubernetes, the thing with documentation is it's a great, easy access point for people. Everybody can contribute to the docs compared to say contributing to multi-tenancy features. You kind of need to know something about multi-tenancy, but also a lot about Kubernetes before you can really contribute to those features.
Um, so when documentation, if we were to propose a major documentation change, on the one hand, every SIG has a stake. And on the other hand, no SIGs have a stake. And on the one hand, everybody can comment. And on the other hand, nobody really has the expertise to comment. So it's the kind of thing, because everybody can have an opinion on documentation.
Um, I don't know that it's possible to drive consensus.
Rich: That's super, super interesting. So, so one thing I've talked about, I think in some previous episodes that is always been interesting to me. So. In my background, you know, I was in ops and SRE for many years. And then there was a short period of time where I thought I wanted to be a product manager. And I was learning about that.
And, and one of the things that's been kind of fascinating to me about Kubernetes is that there doesn't seem to be that product manager role in the way things are structured. Right. You've got like these SIGs that seem pretty self-sufficient, you know, in terms of like the area that they own, but there's, you know, not like the product manager at the high level like, I guess the Technical Oversight Committee, may fulfill some of that, but it's, you know, I don't know.
I don't
Celeste: I don't really, um, my understanding is that the Technical Oversight Committe, their main role is to shepherd multiple projects into the CNCF. Um, and in doing so define the overall technical direction of the CNCF. Their secondary role is to make sure that projects are maturing through to graduation. Um, and again, that also sets the tactical direction of the CNCF. Um, but they don't necessarily decide for the project to my understanding, and I'm not in those meetings. So I don't know. Um, they do not actually decide, um, what product features should be implemented.
Rich: Yeah, no, I think you're right about that. It's been something that interests me because like, you know, with some of the things that have come up in the past, like the issues around the first Dockershim announcement, right. And all the confusion that happened with that, you know, and a lot of that was, uh, from what I understand, anyway, as someone on the outside was a lack of communication between people inside the Kubernetes community, right.
About like what the best way to do this was, and, and those are the kinds of things that I would expect a product manager potentially to help with. Right.
So it's
Celeste: there
is, sorry, off, but there is, um, there is a deprecation process and the deprecation process was followed for Dockershim. And I just want to make that perfectly clear because I think there is um, I wouldn't want to assign blame where it doesn't do. so the people who are actually responsible for doing the deprecation were in fact, doing everything that they, they could.
Um, and I really do need to caveat here. I am speaking as an individual and an individual contributor to Kubernetes, not as a spokesperson of CNCF in this regards. Um, please do not take any of these co. Comments as statements from the CNCF. And if you do um, I, I'm so sorry to the CNCF PR staff, you, people are [inadible] and I love you so much. And they know that. So I'm sorry if this lands on your plate.
Rich: Like you said, I think that by the time this airs, you won't even be working for the
Celeste: I know, but still, I wouldn't want to cause anybody.
Rich: yeah,
Celeste: Um, I think at least from my perspective, and I sort of was brought into it when it was already happening. I think a lot of what people picked up on is it had that word Docker in it. Um, and I think that's why it became as big as it did. The Kubernetes project has done deprecations before it has a deprecation cycle.
Um, are we hoping to make the deprecation, um, process a little more robust as a result? Yes. Um, the thing that I specifically have suggested here. When do you deprecate things you need to A consider the documentation impact and B write a few blog posts during the releases leading up to the actual removal uh, because people just need to keep being reminded.
Rich: yeah,
Celeste: Um,
but
Rich: actually, one of our, what sort of questions was from Rey Is it Lejano?
Celeste: know, I think.
Rich: Yeah. Um, who was, uh, reminding people that Dockershim is going away at 1.24.
Celeste: Dockershim is going away in 1.24..
There is already um, at the time of recording, there is already one blog posts up on this, which is essentially saying Dockershim is going away in 1.24. Uh, another blog posts will go out shortly at some point during the month of February uh, which will be documenting specifically what you need to do to ensure that a 1.23 cluster is compatible with 1.24 after Dockershim.
Um, and there will be, I think, one more blog post, uh, following that up in March, April. Um, again, we're trying to keep it on people's radars this time. So,
Rich: absolutely.
Celeste: but yeah, it's not the only
deprecation that's
going out that release actually.
Rich: Yeah. There've been actually quite a few APIs with
Celeste: Yeah. Again, it's not, it is not the um, it's not the only deprecation of the project is done.
Um, and it kind of goes back to what you were saying earlier, which is in open-source the work that gets done is, has people behind it. Um, and I think that's maybe important for Kubernetes end users to understand is if we are deprecating features that maybe you would like not to be deprecated, need people to help maintain those. Otherwise we have to, because we can't keep maintaining a forever growing code base.
Rich: Sure. Yeah. Um, what about, you know, back to the Kubernetes docs? Uh, what about, um, are there things that you've seen like, um, from a positive aspect in your time there have been improving or
Celeste: I am really, really excited with how SIG Docs has matured over the last year and a half. So, um, prior to its current sort of set of community leaders, um, SIG Docs was run by Zach Corleissen who used to work at the CNCF. Um, and a part of the reason Zach was actually brought in was to help stabilize documentation in Kubernetes.
Uh, and when Zack left his position last year, um, I think they were, um, quite concerned. Um, I was asked not to step into the role as SIG Docs lead very specifically, because there was a feeling that, and I haven't told anybody this, so this truly is the hot news, um, there, and I completely agree with this assessment, which is if I had stepped into SIG Docs leadership at that time, it would have forever relied on CNCF to keep it staffed and to keep it going.
Um, and at some point the community had to take it and run with it and it got rough for a little while there, but I think we're getting there, which is really exciting to see.
Rich: That's
Celeste: the most positive thing is the community.
Rich: That totally makes sense. I can, I can a hundred percent see why, um, why folks would feel that way. Yeah. So you mentioned um, the inclusive naming stuff, which is, something that I've been very excited about. For the folks who aren't familiar, this is, you know, trying to remove, you know, words from the way things are named and documentation and things that, that might be, you know, charged, highly charged for people or, offensive, however you want to put it.
Um, I think that it's, it's a really, a really important thing to do in terms of inclusivity, you know, because as a straight white guy, the things that offend me are potentially going to be different, you know, than, than the the things that offend people with a different kind of life experience.
But, these are efforts that I see sometimes like mocked by people and I don't necessarily want to get into the, those folks, but like, I think there are people who just really might not understand, you know, why this is important. And I'm wondering what, what you would say to someone like that.
Who, thinks that effort, that time involved could be spent better on something else.
Celeste: Uh, yes. The, why are we wasting our senior engineer's time, renaming master branch to main. Um, and I thought that sounded a little derisive, um, because I think it is a very legitimate concern. Um, you know, to that person specifically, what I like to say is, history gets written a certain way. I don't know how else to put it. And in most cases, history tends to look well on people who champion diversity and inclusivity and make an effort to um, to defend people who have less, um, privilege than they do. That is a pretty consistent thing in history. Like even if um, like authoritarianism or racism or xenophobia um, when temporarily, it always seems to be temporarily and there is a long trodden path and history of this kind of thing. So if you don't think it's worth your time, ask yourself how somebody, someone who's going to read your little GitHub comment saying, I don't think we should do this. Ask how that's going to look in 10 years. Um, because for, well, I mean, so another example is, you know, when I and probably you, when we were growing up, using gay as a slur for something, saying like, oh, that's gay, was super common. Super common.
Everybody I know, said those things um, and ask yourself how that looks today. Even if you're not a gay person, like ask yourself, like, does that reflect well? Like, would I want somebody digging through things that I have said in the past and like dragging those up for me? Uh, because you know, we grew up not necessarily with the internet recording everything that we were saying. That is not the case anymore.
And again, if you're going leave that GitHub comment, and this is going to be the GitHub ID you attached to all of your work for the next 20 or 30 years. Like, is it really going to go well for you?
Rich: That's a no, that's a really, really good point,
Celeste: It's not.
Rich: Yeah, I think especially like on the master thing, one thing, that I'll remind people of sometimes is the fact that, there are undoubtably people in this community that have ancestors who were slaves, right. And like how master sounds to you or me may be pretty different to how it sounds to a person in that situation.
And it may keep them from participating in the community. You never know
Celeste: Yeah.
I mean, so Steven started, um, the inclusive naming initiative with me and Priyanka and like a lot of the impetus from that actually came from, so I made comments uh, in June of 2020 during the George Floyd riots. And Steven immediately messaged me and sent me threads that he had started two years ago uh, during Charlottesville stuff, and then threads that he had found from like a year or two before that.
And, you know, It's very tiring for Black people and people of color and minorities of gender or race or whatever, to constantly be the person who has to start their own email threads. And to have to do it year after year after year. Um, like it doesn't seem like that big a theme, thing. It does seem like just words and I get it.
But can you imagine having to do that? Can you imagine having to do that every single time you went to the bathroom? Like there's no sign for me. want me to go? I'm like, I'm so I'm half Filipino. I'm half British, and Vancouver is a city that it, I would say is honestly 50%, if not more um, people of east Asian descent. very often when I was a kid in classes, they would do, they would do the thing where it's like, okay, divide yourselves up. And like, because this was like the early nineties, somebody was like divide yourselves up by race. And so like invariably, people not white. And I just remember it was, uh, it was a summer camp or something.
So the people running it were like 16 and they just didn't think, and it was the nineties. So like, I'm not that upset, but I just remember me and my sister standing in the middle of the room in the summer camp, just like looking at each other, laughing because we're like, what do you want to do with us? Like, we don't even read particularly white. Like we got the black hair, but I also definitely do not read Asian.
Rich: Yeah.
Celeste: And it gets, you know, that was, I was six at that point or something like that. By the time I got to 16, I was over it. It was really frustrating because I had to do it month after month after month, year after year after year. And it seems like a small thing, but over time it's exhausting. So do you want to do that to people?
Rich: No, it's a, it's a great point. And I think that, to me, one of the reasons why I like this community so much is because there, there really are a lot of people who care about these things, who care about making it a welcoming and inclusive kind of community. And, you know, as anyone who looks at diversity and inclusion stuff should understand is um, the, the I part in the DNI is super important, right? Like you can't just bring people in, you know, you need to make them feel welcome and let them know that we want them to be part of the community.
Celeste: I, yeah. I, for me working in open-source and working in a cloud native specifically, one of the coolest parts was like how many diverse people you meet here compared to everywhere else in software. Like, it was so awesome. Um, I always knew that I got along with like the DevOps folks. Like I always just ended up making friends with them at every company that I was in uh, and then when I sort of came to cloud native, I understood why. Like, I'm just why everybody was like this. Um, and it's kind of a part of why I am very passionate about the Code of Conduct stuff is because I don't, again it's, it's those small things. Right. But if you allow those small things to slide all of a sudden into a space where people can't like be.
Rich: Yeah. Yeah. Um, so this is kind of a big, big topic change.
Celeste: okay,
Rich: No, it's awesome. I don't have
Celeste: that's awesome. But like, let's, let's go.
Rich: of that conversation,
But, um, but back to the docs, um, so I think there's a big tendency in open source to not value non code contributions as highly. And I see a lot of people in the Kubernetes community working to counter that, you know. There's a lot of people talking about how important it is to, to just even, you know, fix that typo in a README or, or whatever.
And I wonder, um, what you would tell someone to encourage them, maybe that, that, that's a place they should spend some time, especially a new contributor.
Celeste: From
Rich: Okay.
Celeste: my perspective, particularly for documentation um, the, one of the best ways to learn a product would be working on documentation. Um, have had developers that I've worked with say that I know a feature better than them sometimes. And like when somebody else in the company asks a question, I'll be the one to answer.
Cause I went digging for that answer at some point when I was writing the thing. Um, one of my favorite people in the community is, uh, Tim Bannister. Uh, he is a tech lead for SIG Docs. Um, one of the top contributors in Kubernetes actually consistently um, and just an all around great guy. Um, Tim got into SIG Docs and got into editing the docs when he was studying for his CKA.
He started revising topics and editing topics as a way of helping himself memorize them for the exam. Um, and if, if there was content that he wanted as reference for himself, he opened PRs and got it merged. Uh, so he contributed to the docs for things that he wanted to reference cause you're allowed to have the documentation site open during the CKA
Rich: That's super, interesting.
Celeste: Super super intelligent.
He told us this one day um, I think it was like the last call before, before the winter break. And we were like, Tim, you clever son of a gun. And so this is something that I encourage anybody to, if you're a new contributor um, like if you want to get involved in SIG Multi-tenancy, revise the documentation.
It always needs revision. It always needs additions. If you're, you know, trying to understand how that feature works. And you're, like, wow, how does this one specific thing work? And there's no documentation on it. So you go digging, you start looking through the methods. Um, you start looking for blog posts, you start asking questions, the best way to crystallize your knowledge is by adding to the documentation.
It's just like taking notes. revising those notes for the test.
Rich: That's super cool.
Celeste: Yeah.
Rich: Yeah. I, uh, I think the majority of my open source contributions have probably been things like, fixing something in a README, or I always especially look at those quickstarts, you know, because I, I think that that stuff is so critical. That like, if people run into, you know, they're doing the quick start and, uh, one of the commands, they run it and it throws an error message. You know, they they might just be gone, right. They might invest the time to figure it out. Um, but, but maybe not. And so by by fixing something like that, you're potentially helping so many people, especially with a project as big as Kubernetes.
Celeste: Yeah. Um, and I think this is where Kubernetes is an interesting documentation use case in some ways. Because somebody, it's very possible that somebody won't come in looking to do something specific or looking to evaluate Kubernetes. It may be that somebody has already decided we're using Kubernetes or I'm joining a team that already uses Kubernetes.
And now I need to learn it from the ground up. And it's, I think something I didn't understand about Kubernetes until I really got into it is it's, it's kinda like a set of command-line tools and that's one aspect of it, but it's also a development paradigm.
And in being a development paradigm from a documentation perspective, it also needs to be more like Go's documentation or Rust's documentation than it does need to be like any other open source project or any, any other product. Um, and we're like, a language's documentation, or for example, Spring framework documentation, um, are slightly different in that regards, is they have to teach people the levers they're allowed to pull, for lack of a better word.
Um, so yeah, I think, I think you're exactly right. Um, the quickstarts are super important. Um, the next important thing is how do you step somebody from the quickstart into the knowledge dump phase where you're like, "And now everything." And that's really hard.
Rich: Yeah, Yeah, Yeah, absolutely. All right. Like I mentioned, we've got a whole bunch of these listener questions and uh, I'm definitely not going to be able to get to them all. I want to thank everyone who sent things in. Um, as you mentioned, a few of them were folks who know you and were trolling you about various things but, but most of them, were very, very solid questions.
Um, uh, Our friend Kris Nova, who was actually on the last episode of the podcast uh, had a number of questions. Um, but the, the first one was, what is the biggest problem that technical writers face today?
Celeste: Um, Um, I think that, uh, a combination of being one of the lower paid professions in product and in open source um, uh, as well as being seen as quote unquote non-technical, uh, as well as people having a perception that anybody can write, I went to English for 12 years.
Um, I think the huge, the biggest problem is gathering enough respect to get enough face time with people to do the job well.
Rich: Wow. I can totally see that. Um, I definitely know that it's a role that's, that's undervalued in, in some places. And I'm one of those people who has the opposite view, right. I've worked with some amazing technical writers, and I know what a difference they can make.
Celeste: And, you know, the funny thing is, as I think that's a lot of it too, is there are a lot of people who haven't worked with technical writers. Like somebody else has done the writing because I get that feedback a lot. Like after six months of working with me, I will invariably have a developer often quite senior go to me and say like, wow, like I had no idea it could be like this. And it's a little upsetting, but I think that's, I think it's a huge issue.
Rich: Yeah. Um, so we got a question from Brandon, uh, who is awesome, uh, @bdimcheff. Uh, what are your favorite few examples of great technical writing docs, um, and items for a charcuterie board. So let's maybe start with the technical writing.
Celeste: Um, I still think Stripe's documentation, both their API and non API documentation is fantastic. Um, I, again, I also mentioned Honeycomb, I think Honeycomb did just a fantastic job storytelling around that observability piece. Uh, so shout out to those guys are doing fantastic.
Those people, sorry. Um, uh, And in terms of charcuterie boards, I think it's less about specific meats or cheeses and more about composition. So you need a variety of textures and a variety of like salty savories. So like you got to have some salty stuff, you got to have some cured meats, you gotta have some cheeses uh, but you need to vary the textures.
So salami's kind of a hard texture. Prosciutto is a little softer. Cheddar's a little harder. Brie, nice and soft. Um, both of those are in the salty category, uh, but you've got like salty, salty and then salty creamy. Okay. So moving on, you need some crunchy. That's the next thing you've got to vary your textures.
So crunchy nuts are a good one crackers are a good one. The next thing you need is sweet. Uh, so dry fruits, um, jams, spreads, um, that kind of thing. The charcuterie board is about a variety of flavors and textures. That's what makes it good.
Rich: I think, I'm taking it that Brandon understood your passion for this.
Celeste: Yes. I'm apparently well-known as a charcuterie influencer. Um, I've been off my game this year, but we will return. I promise you.
Rich: All right. Awesome. Um, you mentioned this, this concept of, um, technical writers maybe not being considered technical enough, which I totally get. I know that happens. We had a question from uh, @baskarmib. Um, what is the level of technical knowledge one should gain if they want to find a role in technical writing?
Celeste: Um, at a bare minimum, you need to know Git, you need to know enough HTML, CSS, and JavaScript to manage the static site generator. Very often you are also managing your own build pipeline. So you need to figure that out, whatever that is. Um, if for some reason you step into a role and they're using like Jenkins to build their docs, you either need to find a new job or you need to convince them that they need to move to Netlify.
Cause it's a lot easier. I say this having used Jenkins to build documentation, it was not fun. I was always unhappy. Um, so that is your bare bare minimum. On top of that you probably want to pick up a programming language um, and your first few jobs should be things that code in that programming language.
So I knew Java, my first jobs were in Java based systems. Um, and after that, it doesn't really matter. Um, if you pick up JavaScript, honestly, you should stay within the JavaScript ecosystem for your first few gigs. And then you can expand outwards after a couple of years. You don't need to be a professional, but like if you choose JavaScript, finish freeCodeCamp. I got up to second level, second year Java. I think I had three or four courses in that. Um, you don't necessarily even need to keep up with it, but like, you need to be familiar enough that if somebody tells you launch this thing on the command line, you're not going to freak out.
Rich: Yeah.
Celeste: Um,
Rich: Cool. Yeah.
We had a, uh, pretty much the same question, different wording from Justin Garrison, @rothgar too. So thank you both for, uh, for asking that. Um, we had a question from Christoph Blecker @tophee. Um, if you were queen of the forest, what is one thing you would tell project maintainers to stop doing with their docs?
Celeste: Um, so there's very little that you need to stop telling people, um, it's more what you need to get them to start doing. If there's one thing I would stop, tell people to stop, it's stop using your code as documentation. Um, whether that is like, and I've seen this a couple of times in CNCF projects, and I comment on it every time um, instead of having documentation, you copy and paste the interface or the class.
And like, you just look at the comments for each method. Like, I, I get it, but like it's, and it's not the worst documentation, it's actually pretty clear or you get a description and then you have like the actual signature for the function. It's fine. But like, It's It's bad usability and it's unprofessional looking.
And I think for open-source projects in specific, and I think this is something to internalize. Professionality is super key for open source and super key for gaining maintainers. Um, I once had a, I had a boyfriend once and, uh, he was a pretty silly like senior systems implementer dude. Uh, and he once told me like I don't care how good the project is. If I see that its website is a GitHub README I will not use it because I can't throw that in front of my clients who are paying hundreds of thousands, if not millions of dollars. keep that in mind when you decide to dump your like interface implementation in as your documentation. There is somebody who has very heavy purse strings who will not touch it because of the way you chose to do it. Write it down in a paragraph.
Rich: That's super interesting. Um, gosh, we got so many good questions. Um, there was one from Eric Sampson, @evntdrvn. As a developer, um, well, so, so just to preface this, we both have ADHD, so this is a topic that's pretty dear to my heart. Um, Eric asks as a developer, how to get motivated to write documentation for your stuff, especially if you have uh, ADHD, lolsob.
Celeste: Okay.
So the motivation part and the ADHD part are separate. Um, one, do you want people to use your stuff? You need to write the documentation. If you don't want people to use your stuff, why are you spending your time doing this? It's it's just like, it's it's like mental flattery. It's self flattery, if you don't want people to use the things you write.
So if you want people to use the things you write, you have to explain it yourself. Um, that's your motivation. Dot. Um, as for the ADHD part, writing with ADHD is really hard. I've chosen the worst profession. Um, it is, it is my daily daily struggle. Um, two things. One, the biggest struggle you're going to have as a developer trying to write is that code is node based systems with like multiple connection points.
Um, so like, think about a function that calls another function that refers to a database, right? You're thinking of nodes and webs and writing is linear. You have to go top to bottom. So how do you translate the web to align? That's your main issue here? Um, so you, the first thing you have to figure out is what is my starting point. And then the next thing you have to figure out is how do I logically explain everything that this node based system can do. The easiest way to think about this is think about what is the biggest, most overarching thing you have to explain and write that first and then keep going down the scales. Like, um, we call this like scoping information.
Like you have to scope somebody in basically. So again, for Kubernetes, Kubernetes is a container orchestration tool. Okay, cool. What? Well, a container is dot duh duh dot duh duh dot. When we say orchestration, we mean dot duh dot. Containers consist of dot, dot, dot, dot. To orchestrate them, we have these pods and dot dot dot, and you just kind of keep moving your way down. Um, once you've explained all the things you need to explain, then you just need to list off, here are all the different things you can do. Here's how you, the best way to start with that is CRUD, create, read, update, delete. Um, if there's anything weird that happens after CRUD, explain those things too. And then the final step is okay, what are all the options for a thing?
So if it's a command line tool, what is every single flag, list them out and what they do and what they expect. If it's an API, what are all the endpoints? List them out list out the arguments they expect, list out the expected results. And that's that's the body.
Rich: Yeah Cool. Yeah. I also do a lot of writing in my job as a developer advocate and it can be really hard with ADHD. Um, one, one, hint I'd throw out there is that I think that most of the advice that you see about productivity is not aimed at us. It's aimed at neuro-typical people. And so there are certain things like um, start with the hardest thing that you have to do and get that
Celeste: not. Um,
Rich: yeah. It's
terrible advice for someone with ADHD.
Celeste: So when it comes to writing, when I'm really struggling to get started um, I have two tools that I like to use, and frankly, I often use both. If I'm struggling, one, is it doesn't matter if it's good, just get it out. Like I don't, you just have to get the first sentence out, even if it sounds like utter gobbly, goop, garbage, you have to get it out because at some point your stupid little brain will loop back around and be like, "Oh, that's bad. I'm going to fix it." Once you like, once you've gotten going. Uh, the second, the second is if I cannot figure out for the life of me, how to form a sentence, which happens like way more often than you'd expect, um, bullet points. I just write like, this is the bullet points that I need to cover. Here are the high level topics.
And usually halfway through the bullet point list, I realize I'm just writing full sentences and I just backspace the bullet points. Um, yeah. And then, you know, sit on it for a bit until you hate it and then come back to it And make it, you make yourself not hate it
Rich: Yeah, there's a uh, it's pretty common for folks with ADHD to be perfectionists. And I think that's one of the things that could be a problem is, you know, if you feel like that first draft has to be perfect, you know?
Celeste: It's always terrible. Your writing's always bad.
Like,
Rich: Wait your, do you mean my writing specifically? [laughter]
Celeste: No just, my, my writing too, like. So I wrote a blog post recently that was like my one of my 2021 things I wanted to get back into blogging. Um, and it's fine, but I just I'm like, this is terrible. I write full time and how was so boring and lame and terrible.
Um, so like I do this, like, it's my job. I still don't like my writing. So, you know,
Rich: Yeah. Um, we have another question
from Saim Safdar, @cloudnativeboy, uh, I was on one of his streams not too long ago, he's super nice. Um, he, uh, he asked about, um, the, I had to ask him about the wording here, but I think the, the gist of the question is, you know, if you're someone who's not a native English speaker and you're having to write docs in English?. Are there any kind of resources or, or tips or anything you can think of in that situation?
It's probably a
Celeste: Uh, it's hard. Uh, like, and I worked in Germany where nobody's a native English speaker and it's still really hard. Um, my first piece of advice is just get it out in whatever words you know. Um, honestly, My second piece of advice specifically for people who are not English speakers is if you do not feel that your English is up to the task, talk to your manager. That's not fair. That's not really a part of your job description and say like, listen, my English is not up to the task. You need to hire somebody to do this. Um, I, and You may not be in that position, but like, aside from that I mean, all I can really give you are like really tactical grammar rules, but I don't think that's actually going to be helpful for the fact that like you're writing in not your native language.
Um, yeah. Don't let yourself be put in that position. Tell them, tell your manager that they can pay for an English tutor. If that, if they insist on you writing your documentation, because you don't have the skills to do it.
Rich: Yeah. Yeah.
Um, he had asked too about like, um, how do you, schedule, like your writing? How do you come up with a plan for how to do it? Especially if you're like maybe working on pretty short notice or
Celeste: Um, first things first, the documentation now has to be a part of the timeline. Um, and if that, cause that almost sounds like what that's buried in the question, and I've dealt with that situation many times before, um,
Rich: Oh. Where the stuff just gets thrown over the wall and
Celeste: where it's like, oh, we're
done. We're done because we finished. Yeah, We're done because
we
finished. coding it.
So like. Um, so the first, the first thing is to always make sure that the documentation is a part of the timeline. and pester product management, engineering, leadership, like the CTO, like I've gone like to the VPs for stuff before.
Rich: Yeah. Yeah.
Celeste: uh, cause you're not going to get anywhere until you have the basic respect of being a part of the actual completion.
Um, so the second thing, how do you do it, let's say on a short timeline? Um, ask for help. Uh, if you're being put in a position by your development team where you have to write on a short timeline um, what you have to do for that developer is the second, the second, they check no, like done on that ticket.
You are on their doorstop, uh, with essentially a template document, which is like conceptual, explain what it is. And I, I have sent developers the "blank is a blank that does blank" before like fill in the blanks for me. Um, and then like, okay, what are the steps to use your blank? List them out for me,
um, Three, what are the caveats and gotchas and weird things, are there weird encodings, are there weird like, and just send them a questionnaire, and say like send this back ASAP. it's not ideal. It's not a great way to develop relationships with people, which is a large part of the job. But like, if you're being put in a bad position, you gotta do what you gotta do.
Rich: Yeah. It's interesting because you know, even in my work in developer advocacy, there've been times where I've been working on, on something that hasn't been released yet, right? Like a tutorial for a product that doesn't actually exist yet. It's still in flight and sometimes things can't change. And um, you know, in my case I'm a pretty visual person.
And so I want to see a UI and click on it, right, to like grok something, and that may not be done. Um, what do you do in those kinds of situations where you're, you know, the thing is maybe still in flight, but you really need to get started to be able to finish in time.
Celeste: Um, product management is probably your best friend at that point. And frankly, if they're asking you to start something that early, that's still like technically in flight um, they should have enough information that you can, can fill out the conceptual parts rather than the actual step-by-step implementation.
Um, and if they don't, um, I think you push back, and say like, there isn't enough information for me to work. Or if they give you an explanation, they're like, oh, but 50% of this might change when we implement, like you push back and say, that's a waste of my time.
And you need to come back to me when you have enough information uh, that we can be 75% sure that it's not going to dramatically change.
Um, And even for stuff that is still being implemented like, again, I feel like if product management has done their job correctly, like you still have a rough idea of what the steps for you tutorials should be. Like, you can look through the tickets and say like, okay, like, we're going to use a command line tool. We're going to do some SSHing. We've got to write a config file. We don't know what the configs are going to look like yet, but like, we're going to write a config file. Um, yeah, this is roughly the shape of it. Uh, and then as things get finished, you fill in the blanks at the end, you test it and hope.
Rich: Yeah.
Celeste: But I do not believe in allowing people to put you in crunch time as a writer.
Rich: Yeah. Yeah. Yeah. I agree. It definitely seems like product management is the kind of, or the kind of folks who should be making sure that you have time to do your work. Um, one more from Kris Nova. Um, there are a lot of non-technical writers out there writing docs. What are some small things that non formally trained writers could do that would have a huge impact?
Celeste: Hmm. I mean, there's a role for, for everyone. Um, where are you going to get the most bang for your buck with a technical writer is, um, making sure that the documentation is structured in a logical way, making sure that the documentation is complete and actually friendly from a user perspective. Um, and again, making sure the actual use case is covered. Um, please note that all of those things do not necessarily involve code.
If you are not a technical writer who is writing a documentation, the place where you can be most valuable and contribute most in terms of a team setting is writing sample code, because I could be, there are a lot of technical writers who were at one point software engineers um, and they're, they're in technical writing for a reason.
They didn't want to be software engineers, just like most software engineers don't want to be technical writers. Um, writing good sample code though is the key. Uh, you see a lot of sample code where like in a class name foo has a method name bar, and that's useless, people, it's useless. Um, uh, for example, and I used to have to tell people in e-commerce all the time, it's like you can't, you know, call your new method for an e-commerce API car. What does that? That's not a feature that an e-commerce user is going to add. What is a feature that they might add? Subscriptions, reccurring subscriptions services. So I think helping understanding your user and brainstorming realistic sample scenarios and then creating sample code around those scenarios incredibly useful. Um, and if you comment up your code well enough, a technical writer can fill in the gaps and like together you can create something very, very beautiful. Um, Kat and I were going to give a talk on this and, uh, it didn't get accepted,
Rich: Oh, no.
Celeste: but maybe one day we'll figure it out.
Rich: Well, I do hope to see you give more talks. Um, I'm hopefully going to be at Valencia if uh, I'm able to travel. So we'll see. I don't know if you,
Celeste: So fingers crossed here. Um, I mean I submitted one talk, um, and in case it doesn't, I don't sure if I'm allowed to say what the talks about before it gets announced.
Rich: Oh, I don't know.
Honestly.
Celeste: I submitted one talk. Uh, I have another talk that I want to submit for a maintainer track. Um, and I have a couple of talks, um, I'm thinking of submitting one talk to Write the Docs this year, and I'm thinking of submitting a few to Open Source Summit.
So if I'm allowed to travel, we'll see.
Rich: Very cool. Well, um, I think we'll wrap it up there. I want to thank everyone for all the great questions. There really are even more than I had time to get to. And um, it was so much fun to be able to, to work those in. And, um, I want to thank you Celeste for taking the time to come on to chat with me. I think this is the first time, like you and I have been on calls together before like random Zoom calls and things, but I think this is the first time that we've had like a one-on-one conversation with this, like this and
Celeste: Oh, but it's fun.
Yeah. So thank you for having me.
Rich: Yeah. I really enjoyed it.
Rich: Kube Cuddle is created and hosted by me, Rich Burroughs. If you enjoyed the podcast, please consider telling a friend. It helps a lot. Big thanks to Emily Griffin who designed the logo. You can find her at daybrighten.com. And thanks to Monplaisir for our music. You can find more of his work at loyaltyfreakmusic.com. Thanks a lot for listening.
