Not Just Documentation With Mary and Kimberly

Transcript

Mandi Walls: Welcome to Page It to the Limit, a podcast where we explore what it takes to run software in production successfully. We cover leading practices used in the software industry to improve the system and reliability, and the lives of the people supporting those system. I’m your host, Mandi Walls, find me @lnxchk on Twitter. Welcome back for this week’s episode of Page It to the Limit. Joining me today, I have Mary and Kimberly. We’re going to talk about documentation, good stuff like that. Ladies, tell us a bit about yourself, Mary, who are you? What do you do?

Mary Jinglewski: My name is Mary Jinglewski, and I am currently the Instructional Designer and Technical Writer for Honeycomb.io.

Mandi Walls: Awesome. And Kimberly?

Kimberly Garmoe: I am Kimberly Garmoe. I am currently unemployed in the best possible way. I was the manager of technical documentation at Chef until last Monday. And on April 4th, I will be starting my next job.

Mandi Walls: Excellent. So you’ll be reemployed by the time this episode comes out.

Kimberly Garmoe: I’m unemployed in a non scary way.

Mandi Walls: Yeah. Fun employment going on.

Kimberly Garmoe: Unemployment time for myself.

Mandi Walls: Excellent. Awesome. So tell us a bit about what you kind of do day to day. For folks who maybe aren’t sure exactly what kind of things that an instructional designer and technical writers and what is this job? Mary, do you want to kick us off?

Mary Jinglewski: Sure. So I’m technically half of a person with my roles. So as an instructional designer, a lot of things that I do involve working on public workshops. You may know about our intro to observability workshops that we have, our advanced observability workshops. Part of my role was to develop the curriculum involved with that. That was definitely a collaborative project with subject experts at Honeycomb. In addition to doing that, my technical writer role focuses on all of the content and information architecture and so on and so forth that you can see at the Honeycomb doc site, which is docs.honeycomb.io.

Mandi Walls: Cool. We’ll put some of those in the show notes, because I know Honeycomb, you run those workshops on a regular basis. We’ve had some other honeycomb folks on the show before so.

Mary Jinglewski: Correct. Yeah. Usually I believe the intro to observability or observability 101, runs on a monthly basis. I know 201 will be coming soon, that’s all.

Mandi Walls: Awesome. Well, we’ll post the page and if folks want to check that out, that will be awesome. And Kimberly, since you’re between jobs, like what were you used to doing and what are you looking forward to doing?

Kimberly Garmoe: In the most last year at Chef, I managed the technical documentation team. And in the four years prior to that, I worked up from starting out as an in individual contributor to team lead, and then into management. I focus on user facing documentation for our customers and for our community. Typically, in the Docs as Code methodology, though not exclusively. And the areas that I really specialize in are classification, taxonomy and page design. So that content is consistent and discoverable, and also findable through both Google and whatever internal search you’re using. So I’m a big old search nerd.

Mandi Walls: Okay. All right. Well, so what was the method you mentioned?

Kimberly Garmoe: Oh, Docs as Code?

Mandi Walls: Yeah.

Kimberly Garmoe: So the Docs as Code methodology is easy to think of as DevOps for documentation. It is a way of writing and publishing documentation that is consistent with the values of DevOps. That is it is, iterative, deployable and repeatable. And secure and reliable in so far as possible. And it means that we collaborate with engineering teams. We enable engineers to write and we do a lot of writing ourselves.

Mandi Walls: Okay. I hadn’t heard about that before. That’s awesome.

Mary Jinglewski: Oh, it’s a really great philosophy especially if you are a loan docs writer or if you’re starting out in docs. It’s a great way to make sure that your docs are getting up to steam. And also that there’s different processes that are streamlined and automated.

Mandi Walls: Okay. So everything you want for your code, you want for the documentation that describes?

Mary Jinglewski: Correct. And ideally the documentation would be as close to the code as possible. So, some techniques with that involve like your documentation is held in the same repository as the code that you are writing.

Kimberly Garmoe: And the tools that you use for writing your documentation are tools that are developer friendly and it’s easily accessible for developers. So it generates marked down files, if you are using automation, it’ll generally be [inaudible 00:05:03]. Sometimes [inaudible 00:05:04] but that’s truly if it’s a hands off experience, like nobody has to mess around with it. And you have automation for testing code snippets wherever possible, and those things then get ingested automatically into your codes so that they’re always reliable. You’ll use standards on such things like as APIs. So your APIs will be documented using the open API standard, which means that you can test them, push out to the open API standard, that document. And then your API content is published using that document. There are tools for that. And it’s a question of how do you build? How do you test? How do you deploy?

Mandi Walls: Yeah. So it’s similar to what you hope your software engineers are going through the same thought process there. So how did you get into this? Mary, I know your background’s kind of interesting. How did you get to where you are now?

Mary Jinglewski: I got to where I was because of Kimberly.

Mandi Walls: Oh, so we’ve got a partner story here. Okay.

Mary Jinglewski: Yeah. Well, I was thinking about it Kimberly, and I think we’ve met, it’s either going to be this fall or next spring. We’ve known each other for a two digit number of years.

Kimberly Garmoe: Yeah. let’s not say those words out loud.

Mary Jinglewski: Yeah. I’m going to put an actual number, I’m just saying like it’s a visible number. And Kimberly and I met in graduate school when we were getting our master’s in Library Information Studies degrees at University of British Columbia.

Mandi Walls: Okay. So your background is in library science, is that?

Mary Jinglewski: Correct?

Mandi Walls: How does that translate? What do you bring from that background into what you’re working on now?

Mary Jinglewski: Oh, there’s so much. Like every time someone goes like, oh, Mary, do you know of any technical writers? I’m like, there’s a lot of librarians who are looking to get out of libraries that would be assets for your company. There’s a whole bunch, anything from project management to content creation, especially for aspects with the instructional designer part. Any librarian who has done instruction or instruction whether it be workshops, tutorials, so on and so forth. There’s difference specializations within libraries. But a lot of times, librarian roles can encompass many skills within one job. I’m holding myself back because I know Kimberly is going to be like, let me break it down with not only that, but taxonomy and information organization and boom, boom, boom.

Mandi Walls: Well, yeah, let’s talk about the vocabulary words there. Yeah, go for it.

Kimberly Garmoe: So I started out, my travel to technical writing is even [inaudible 00:07:45]. That as I started out as an academic in the humanities, so I spent the first part of my career writing and teaching engineers to write. That was surprisingly enough, a skill that I already had practiced. And when I left the academy, I went into library sciences. Mary said this is where we met. Really, so much of librarianship is directly translatable to what we do as technical writing. We’ll say there are three parts of librarianship. One is technical services, another is user says, right? And then the third is really what Mary specializes in, which is instructional services, right? So within all of that we share a couple of core classes, a couple of core real trainings. The first of which is, we are trained to have a user oriented and service oriented mentality. That is what we call professionalization. It’s very hard to learn, right? In library schools is a lot about knocking off the rough edges, because you have to be able to remain cool and calm no matter what is going around you. Right now, you can go into the back room and lose your mind, but in front you are collected. You don’t have that option, your option is always to speak in a nice voice, be welcoming and accept that whatever your challenges are, the person coming to you their challenges are at that moment your priority.

Mandi Walls: Yeah.

Kimberly Garmoe: So in technical services we learn three great things, right? We learn taxonomy, well, first classification taxonomy, and of course, databases. I know every librarian you know can create a database from the command line, right? And has been able to do that at some point in their career. So if you have somebody right at a library at school applying for a database job, you should look at them. Because even if they don’t have the credentials you want them to have, they already know how to do it, they’ve passed that class.

Mandi Walls: Oh, interesting. Okay.

Kimberly Garmoe: So that gives us an introduction really into data and what data looks like, and very specifically, what metadata looks like. Classification is what kind of buckets we can put metadata into. And then taxonomy has a lot to do with how we present that, right? So your taxonomy is like your left navigation on your site, also your page navigation, but also primarily your left navigation on the site on the web. There’s all the kinds of context to do taxonomy. And when you put your music on your shelf and you put it in an order, that’s not just greatly off alphabetical, right? You’re using a taxonomy and you’re classification. It’s a theoretical construct of how information should exist for a user or for more users. When you’re doing your private collection, you can do it anyway you want. Autobiographical, that’s amazing, nobody else can find your stuff. Doesn’t mean there’s not an order, it’s just not discoverable for other people. And so again, that emphasis on service and on the user that was pounded into us in library school is how we think about how to present that information.

Mandi Walls: Interesting. And so, what do the parallels look like between your sort of like baseline user service, that sort of thing, and applying that for folks like you both have been working for software companies and providing technical documentation, technical information to a technical audience. Is it different? Does it relate? Is it similar to similar?

Mary Jinglewski: I will say with user services, one aspect is reference services. Which is when people come to you asking a question. We both took a whole semester’s worth on reference questions. The big takeaway was the first question is usually not the actual information that is being looked for. So the first question is just the beginning of the path that may reveal that the user actually would like something different in their information search to be found.

Kimberly Garmoe: Yeah, it’s called a reference interview. And so it’s a way of strategy of talking to people to help find out what really is the problem that they’re trying to solve. So, somebody comes to you and says, “Where’s your API documentation?” And you can say, “My API documentation is here, what are you looking for?” And then they’ll say, “Well, I need to know how to make the SDK do this thing I want it to do.” And you understand at that moment, they don’t really want your API documentation. What they want is your command line documentation, your SDK documentation. And then you can purse it through and figure out how you solve that problem to help enable them to do the things they need to do in the simplest and fastest way. So other things that happen with the user services, the first point is, is the ability to parse what kind of user is asking you a question. If it is a user with a fairly low or new level of information with your product, and a user who is already an expert in some realm, possibly not in your product and a user who is an expert in your product. And the ability to satisfy information needs for each of those audiences. It’s one of the things that we challenge ourselves to do in documentation.

Mary Jinglewski: And with the knowledge of personas and how users interact with information differently, that really lend a lot of advantages at least with the librarian background to figure out, hey, what do our users really want? What information are we presenting currently within our documentation? Do our users actually find this information interesting, or not interesting but valuable?

Mandi Walls: So do you end up then working with like product teams and those folks to say, okay, what do your personas look like? What are they looking for? What are you expecting them to need to do in the product and then translating that back into the document?

Mary Jinglewski: That’s one aspect. And also there is a function or a specialization within librarianship with liaison roles. So in an academic environment, there may be a librarian who is responsible for the chemistry department, or the science department. And so, they become somewhat of a subject expert and they provide services and support to those faculty members and to students within that department. And you learn to meet those users with their needs and also to plan projects and how to spend many plates at once. So that’s really handy especially if you’re in a role such as a technical writer, sole technical writer, and you’re having a bunch of contribution from a bunch of different engineering teams. Those skills really lend itself?

Mandi Walls: Cool. What can engineers do then to help you out? Like as they’re creating new features and doing all this work that they’re doing on the products, what creates less friction then for getting the next step out?

Kimberly Garmoe: So that depends a lot on the way the writing is organized, right? And specifically how many writers exist within an organization? If writers are part of the team, if writers are separate from the team, if the ratio of engineers to writers is staggeringly high, these things all impact the way the work happens and who needs to do the work and the rate of release. So like anything else, if something… If there aren’t enough writers, if writing is undersupplied, then there will be more bottlenecks. Because you can’t expand the throughput I think I’m trying to say without making the pipe larger. So if a new feature is coming out, feature documentation is oftentimes nice to have when it’s released into the world, not just in the release notes. Ideally, the writing team is made aware that the feature is coming out. If the writing team is responsible for documentation for the feature, it needs to be done in a timely way for the writing team to become educated that is informed about what the feature is and how it works. Otherwise, the engineering team needs to be responsible for it. And few Docs as Code methodology that’s easily done with enough time for the writing team to test out the documentation, to give the thing a whirl and validate it, as well as reshape the pros and go through the process of writing. And writing itself is a skill just like coding, it didn’t come out of nowhere. We’ve practiced and honed it for now at least, two digits worth of time Mary. And that has to be respected as a process as well and as a skillset.

Mandi Walls: Yeah. So as teams are working at their breakneck pace, I know when I am digging around in the documentation for a product and the latest features aren’t there. You sent me this press release, I got an email, but you haven’t put the user document. It’s so frustrating, right?

Kimberly Garmoe: It is. So what that speaks to is a gap in content strategy.

Mandi Walls: Yeah.

Kimberly Garmoe: People were aware that they needed to have release notes. And had a feature therefore they were going to release it and there’s going to be release notes. A lot of times that’s fairly automated from a change log. And marketing wanted to put up some fanfare about the new features, but nobody told documentation, right? So that really is a point at which the content strategy for the company isn’t working and you should address that gap. Like who needs to be brought in to this room? And how can we address whatever problems we have that might be blocking publication, the timely publication of information?

Mandi Walls: Do you have any advice for teams who are maybe struggling? Because I feel like it’s probably not just throw more tech writers at it, it feels like there’s maybe a bit more process and thinking to do.

Kimberly Garmoe: Well, I’m going to say a lot of times it is throw more tech writers at it. The way in which technical writing is understaffed in relationship to the work at most places is dramatic. And having more writers making that infrastructure, the writing infrastructure larger solves a lot. Coordinating with technical writing about releases would be the second core part of the strategy. That there’s going to be release in a month about this thing. And we are going to have the code at a certain date. There will be testing after that date. And that’s when the writing review can happen. But this means very importantly, there has to be a little bit of a gap between the time you push what you think is going to be your production release, and its actual release to the public. And that’s when we can catch up on that. Now, if you want to do writing as you go and have editing as you go, then you certainly need to have enough writers to make that happen. Because that’s a much more labor intensive model, writing labor intensive model.

Mary Jinglewski: And I know Kimberly having worked together at the same location, I know in transitioning to Honeycomb where we have things like test and prod and I guess, there’s version numbers. But nothing that’s publicly, so it’s like we’re always iterating. It’s very interesting because with technical documentation, that takes on a whole another level in how you have to approach the technical documentation. So as Kimberly said, you have to coordinate with your teams. You have to coordinate with product, you have to coordinate with marketing. Ideally, do we know of something from one of these three locations? And so it’s been an interesting process because addition to having that communication, what’s really important I find is having an established process. Especially as like the so docs person. One of the first things that I did with my managers support is to create a new process, write it down, be able to talk to all of the teams that would be potentially involved in creating content to say, hey, this is our process, this is what’s going on. I know at Honeycomb we also have an internal volunteer doc skilled that we have. Full of wonderful folks from all sorts of different departments, that bring their expertise and their enthusiasm about the docs. So we meet and we have discussions and we work on documentation together and different initiatives which has been really nice. I know not everyone can do a doc skilled, like right now, Honeycomb is relatively small. We’re growing significantly in this year and hopefully the coming years. But it’s one of those things where it’s like, okay, we’ll see how this structure works for now. But if you are a smaller organization, there’s ways of being able to formalize and create a streamlined structure. So then it becomes normalized in terms of, oh, yes, documentation, it’s not a big scary thing of submitting this content. Because I know the docs writer is going to go in and look at what I wrote. It’s they’d rather have the content than nothing at all. They’ll help me polish it, they’ll help me figure out where the information needs to go. It’s about crew that trust and that community around the documentation.

Mandi Walls: Yeah. That’s interesting. I figure a larger organization, a larger engineering team is going to have guilds around certain components or languages or things like that. Like, it feels kind of natural to have, if you’re interested in this, if you’ve been frustrated by it in the past like maybe I have, on both ends. Because full disclosure before either of you joined us at Chef, our docs were a nightmare. And I had my dirty fingers in there for a while and it was not my most favorite thing to do either.

Mary Jinglewski: And that was it with at least like five years. I’ll be generous and be like, yes, it was five years worth. At least five years of content and version changes and new features that may or may not have been documented. I know by the time Kimberly got done with it was good to go, but like-

Mandi Walls: Oh, it’s amazing. It was an absolute revelation for us I think, because it had been so catch as catch can, and written by the field team, and written by the consultants, and written by whoever else. Looked at the thing and said, this isn’t actually how this works and we should fix this documentation so we can stop answering questions.

Mary Jinglewski: Yeah. And what I appreciate with the Docs as Code philosophy is that not only are you getting contributions from engineering, but also those who are out in the field. I really encourage that because my background was before Chef, I was a trainer for a open source library software. So I would find things in the field where I would go, wait, that wasn’t there. And then the developers would be like, oh yeah, it was there, we just didn’t write about it. I’m like, okay. At least I know this for next time so it doesn’t surprise me, but like I need to write it down for the community so.

Mandi Walls: Yeah, definitely. So that’s the question too, for the companies that you’ve worked for and especially with Honeycomb now, there’s a lot of user activity, the Honeycomb Slack is pretty busy. Do you have a way that you take input back in from customers and users as well as the content that comes through the regular development pipeline?

Mary Jinglewski: Oh, for sure. Well, at least for Honeycomb, those who have been on the Honeycomb doc site recently may have noticed a little feedback form that has started to appear at the bottom of all of the pages with the exception of the homepage.

Mandi Walls: Very nice.

Mary Jinglewski: And that is a recent addition that we’re really excited about. And we’re also, I know at Chef the docs repository is public so that there could be community contributions. Honeycomb, it’s still a private docs repo, but we do have a… Oh, I need to update, we have a docs email now for feedback. But we also have the feedback form. The big thing is the feedback form that everyone in doc skilled sees anyway. And we also have suggestions and fixes and things pointed out to us within our Honeycomb Pollinator Slack, which is our community group Slack. So that’s been really helpful. So we’ve been getting information or getting information from a whole bunch of folks and we try to respond as fast as possible. I know having someone that’s responsible just for docs was a big deal, because then it could be like, oh yes, this one little fix will actually get fixed. But my thing is always the generosity of our users that I appreciate. Whether it’s internally or external, our users are really passionate about documentation. And that’s been really nice to experience at Honeycomb.

Mandi Walls: All right. To wrap up, do you have a favorite myth you like to bust about the work that you do? Are there things that you find folks really have a misconception about or have the wrong idea about that just want to set the record straight right here?

Mary Jinglewski: Well, I was going to say at the first part of your question, I was like, oh yeah, myths for ex librarian. Yeah. I don’t have a favorite book or book recommendation, but ask me maybe in three months when I’ve read a book. That was a question that I, or something that I experienced when we had an internal AMA at Honeycomb. Everyone’s like, what’s this? What’s that book? And I was just like, it’s been a while.

Mandi Walls: We have to have a book chat on a different episode, we’ll do more prep for that. Yeah, definitely.

Mary Jinglewski: Except, well, it was one of those things where I was like, oh man. I used to have opinions about that, but they were like, “What’s your spicy hot take?” I was like, I don’t know. There’s like a children’s illustrator that I think is cool, but I don’t think he’s that cool. Which is like controversy among the children’s librarians that I know so.

Mandi Walls: They have their own set and Twitter and like things get real weird over there.

Mary Jinglewski: On Twitter, do beware. Please be careful when waiting through. Library Twitter is a very formative space and informative space, but there are flame wars.

Mandi Walls: It’s spectator only for me.

Mary Jinglewski: You are a wise person.

Mandi Walls: Yes. Kimberly, anything on your side?

Kimberly Garmoe: So I’m not going to give a hot take, but the book I would recommend is Bhatti’s recent book, several authors, but the first author is Bhatti, B-H-A-T-T-I and it is Documentation for Developers.

Mandi Walls: Oh, excellent. Okay, we’ll put a link to that in the show notes. So for developers that are out there, if they need to maybe have some language to justify doing a little bit of additional work on documentation to their product teams or anything there, do you have any recommendations for them as our parting thoughts today?

Kimberly Garmoe: It always seems incredibly strange to me that you would need to justify documentation, right? I mean, if nobody has it written down, if it doesn’t exist somewhere, the feature may as well not exist, right? You’ve rendered it invisible.

Mary Jinglewski: For the product team, docs can be the difference between people using your product, your influence of your product expanding. They can really be a differentiating factor within the market.

Mandi Walls: I feel that way too. Absolutely. And like I said before, when you guys came on board at Chef and helped us out there, it helped all of us in the field to get things through to the users so much better, and give them a place where we couldn’t be available 24/7 for questions and concerns that they actually had a reliable place to turn for answering the questions.

Kimberly Garmoe: And also finally, thank you so much for all your kind words about out my work at Chef. I always see the words instead of-

Mandi Walls: I know, right? It’s one of those crazy things, especially for startups I think. The early versions of anything are almost an archeological project. They are almost like a baby scrapbook. You’re flipping the pages and seeing how things develop. And then all of a sudden your product is walking and teething. And you haven’t really caught up with what’s going on with the documentation.

Kimberly Garmoe: That is the best analogy.

Mandi Walls: Good. We learned something today.

Mary Jinglewski: Yes. And don’t be surprised if your technical writers are like, oh yes, but it could be better. Because that is usually my default risk sponsor as well when it comes to any technical writing that I’ve done. I’m like, thank you very much, but it could be better. I appreciate that you enjoy it, that you have found use. I love highlighting other people’s work though. There’s a podcast that recently had a guest that was like, “Oh, Honeycombs conceptual documentation is really good.” And I was like, that wasn’t me, but I’ll be sure to let you know the main contributors to that, they got a shout out.

Mandi Walls: Excellent. Fantastic. All right. Well ladies, thank you for joining us. This has been super interesting. I will make sure that we have all the amazing resources in the show notes for folks because the Docs as Model and the Bhatti book, those sound absolutely crucial references for folks who are interested in these things. And I thank you for joining us today. This has been great.

Mary Jinglewski: Yeah. Thanks for having us.

Kimberly Garmoe: Thank you.

Mandi Walls: All right. For everyone else out there, we will wish you an uneventful day. That does it for another installment of Page It to the Limit. We’d like to thank our sponsor, PagerDuty for making this podcast possible. Remember to subscribe to this podcast if you like what you’ve heard. You can find our show notes at pageittothelimit.com and you can reach us on Twitter @pageit2thelimit using the number two. Thank you so much for joining us and remember, uneventful days, are beautiful days.