Mikey is a technical writer at Red Hat and gave the keynote at DjangoCon Europe 2019 on documentation. We discuss how to get into technical writing, her work on Write the Docs, and more.
Will Vincent 0:06
Hello, and welcome to another episode of Django chat, a weekly podcast on the Django web framework. I'm Will Vincent joined by Carlton Gibson, hi, Carlton collar will. And this week we are very pleased to be joined by Mikey Ariel to talk about technical writing. Hi, Mikey.
Mikey Ariel 0:18
Hi, Carlton. Well,
Will Vincent 0:20
hello, Mikey. So we were just discussing off air you were a number of hats. What are you doing today in terms of helping developers write better technical docs?
Mikey Ariel 0:30
Well, so the first thing I do is actually write technical docs. So I'm a senior technical writer at Red Hat. And I work on OpenStack platform. And the other thing, the main thing that I do is I'm also on the core operations team, global core operations team at write the docs. So we organize conferences, meetups, we have online spaces for anyone who cares about documentation content, communications. So on, mainly in the software industry.
Carlton Gibson 1:02
Can you tell me a little bit about write the docs? Because that came out of read the docs? And can you tell me the history and the relationship?
Mikey Ariel 1:08
Yes, of course. So the co founder of write the docs is also the co founder of read the docs. So Eric culture is the person who started basically both with a few other people as well. And now he's involved with both. So we're both on the core operations team of write the docs, but he is still running, read the docs with a different team. So he basically has two projects or venture.
Carlton Gibson 1:34
The other thing that Eric came up with was the famous Pac Man rule, right? But conferences
Mikey Ariel 1:38
Absolutely. And I love the Pac Man rule. This is one of the traditions we have at right, the docs, which I'm a big fan of, and I think it's something that can be very useful to any communities, any places where you have conferences or a bunch of people who don't know each other who get together
Unknown Speaker 1:56
so we do they want me to run down. We do that. Yeah, you
Carlton Gibson 2:00
can tell us a little bit, but we do that Django con, too. And it's one of the things that I find really cool, because it just opens up. But yeah, to tell us in case listeners don't know what the Pac Man rule is,
Mikey Ariel 2:08
okay, that's great to hear that you're doing it in Django conferences as well. Pac Man rule is basically a social helper, where if you're standing in a group with, you know, two, three more people, you should always leave space, leave some of the circle open, for someone to join in. And so your circle ends up looking a little bit like a Pac Man. And it's basically giving people explicit permission to approach groups, join conversations, and to also accept new members into a group or conversation. So it's basically saying you can do this and don't be afraid to join a group and meet up.
Carlton Gibson 2:45
It really works well. So that's cool.
Will Vincent 2:47
So I want to ask about your background, Mikey. But before that, how does one what are the standard paths to get into a technical writing role, or their standard because I could see someone coming from Writing and then learning some programming to do technical writing, or maybe a programmer who decides they like writing more, though that's maybe less common. What are the? How does one get into technical writing?
Mikey Ariel 3:10
Well, it's funny, you should say that because up until recent years, there hasn't really been a standard path to technical writing. I guess I can compare it a little bit to what's going on nowadays with data science, because a lot of people come into data science, from programming from, you know, from statistics, from math, from science from all different kinds, but there's no like, nobody's really teaching it in the universities. There's no degree in data science yet from unless some somebody came up with it. But as far as I know, it hasn't come up yet. And so technical writing for a long time, was kind of like that, even though it's quite an old, relatively old profession. As soon as developers realized that they have to document what they're coding. Then somebody had to come up and do it. So there have been technical writers. Yeah. There have been technical writers since you know the 60s or 70s, I actually met a few of them. Somebody gave a talk about the history of tech writing. And it used to be binders that you have to use whiteout and take out a page and put it back. It was awful. But generally, up until recent years, if you wanted to be a tech writer, there hasn't really been a strict University program. Somebody might learn a technical writing course as part of Computer Science degrees. But what actually happens is people who are drawn to the tech industry, but who have a strong linguistic background, a lot of tech journalists, people who studied English people who were doing I mean, we've I've met people who've basically retrained as technical writers, and I've done the same thing, because when, before I was working in tech writing, I was working in Television, I was doing production management. I was doing video editing I was doing, I was working all kinds of administrative things around the broadcast industry, which was another passion of mine. But I basically went by the route of private, sort of placement company, that they basically outsource contractors for tech writers. And they offered an internship combined with a course. So I did 20 hours a week for four months at a tech company. So that was my internship. And then I also did one day, a week of classes, and the course was free. And then they got a free intern. And that's how I got my first job. So that was a little bit how it worked back then. Yeah, yeah. So there are a lot of ways to get into technical writing. I think the best combination is to have a technical talent so to know your way around technology and to have a really strong, linguistic grammatical skill, because that's the part that really makes the difference between, let's say, technical writer and developer, right? Because we deal with words, right? That's the main thing.
Carlton Gibson 6:16
But you also said something really done quite controversial was that we have to document our code. Now, you kind of implied that that was true. It's so yeah, Carlton's is so clean it documents itself.
Mikey Ariel 6:29
No, no, I'm joking document. Yeah. Self documented code is code you wrote recently. Yeah, that's my that's one of my favorite controversial things to say go do today.
Carlton Gibson 6:39
Even Yeah,
Mikey Ariel 6:40
yeah. Well, I think that in general, it's not necessarily see that's the thing, right? There are different types of documentation and documenting your code is not necessarily, you know, putting in help strings on every single function that you write, although that could be useful for other developers who are listening So using your API, or things like that, but if you're looking at the end goal of any software development is to have somebody use the software. Right? So unless you unless you have a such a simple tool, and you're working with people who have the same background, I mean, a specific background, just because they're developers, doesn't necessarily mean they'll understand what you made. Ultimately, you have to explain what the goal of your code is your software, what can the user achieve with it? You know, and and why should they even use it, and how to use it. So those are all things that should be documented, even if you don't document every single function in detail.
Carlton Gibson 7:46
Like any piece of code you go to, you know, you find a repo on Hacker News, you click through, you end up on GitHub you need you need a decent introduction, right? You need a decent get README or you need a tutorial or getting Started or
Mikey Ariel 8:01
exactly something exactly, you need to find a way to capture the attention of today's modern, impatient and smart user. Right. And if your users are developers, you still look at them as users because they use what you made. And so it's a part of your selling point is to have a good hook. And it that's where technical writing even though it's, it's technical writing, it's still a very big part, and should be a very big part of the marketing strategy for your software product.
Will Vincent 8:38
Right. Well, marketing is another thing that I think developers are famously bad at. So
Mikey Ariel 8:43
yeah, I mean, I wouldn't necessarily say they're bad at it. They're just not experienced, right? They didn't specialize in it. This is one of the things that that I always try to defuse a bit of anxiety or resistance when I talk to Some developers because they say, Oh, well, I'm terrible at documenting I should I'll never do it.
Will Vincent 9:05
Right. It's like the equivalent of like, I'm not technical.
Mikey Ariel 9:08
Exactly. I mean, I had, I had zero experience with Linux before I joined Red Hat in 2013. I was working as a technical writer for mainly Java. And before that, C sharp, but I used IDs for all my doc strings. And you know, I never really worked in a terminal, but I had a good foundation as a technical writer, and I had the open mindedness to learn new things. And now my default operating system is Fedora. I never thought I'd be there. And I always thought I was not very technical. So, I mean, it's just like, but the thing The reason I mentioned this anxiety or resistance, is that a lot of times developers forget that. They specialized in a different skill set. And so it's okay to not be an expert in documenting your code. But if you can learn, if you want to learn, that's the thing, right? There are different ways, different levels of expertise that you can get to. For example, I choose not to really learn how to code because I was never really as drawn to it as much as I was to technical writing. And that's not to say that I'm I don't have the, you know, the most respect and awe from people who can code really complicated and amazing things. That's great. That is just not my field of expertise. And I, I choose to focus on tech writing because I like it more.
Will Vincent 10:45
What I would call mo curry. I wanted to ask you maybe a meta question that I think a lot about since I wear both hats of writing and programming. And that is what's the difference between a documentation and tutorials or do you think there's a distinction Now I'll tee that up in the context of, you know, so with Django, Django has fantastic documentation. But I've seen more and more that showing how a tiny piece works is different from showing how to use it in a larger context or perhaps providing advice, which is more, you know, basically what I write is tutorials. And it took me a long time to understand why the Django Doc's and other Doc's weren't tutorials, but now with experience, I see ICD, each has its place. But that's, I think, a distinction that takes some time to internalize. I'm curious if that resonates with you.
Mikey Ariel 11:31
Yes. And that's actually something that has been going on in the industry for quite a long time. I think. I've been a technical writer for 10 years, and maybe a few years after I started. There came a huge wave of basically shifting the focus or reprioritizing the types of documentation that you provide, and this is something that we still struggle till this day. I mean, this is Not absolutely we didn't solve this problem. So just as a side note, and because I'm a writer, I'm going to say this documentation as a term, it is usually referring to all types of documentation. So what you're specifically talking about is reference documentation. Right? So, but Django project treats it, like the documentation. So it's actually misclassified or the the term is not the most accurate, but we'll have to
Carlton Gibson 12:32
have to come to a difference there. We do have topics and tutorials and reference in different sections and you know, there's how tos and the you know, there are there have been historically attempts to break this divide, but I think we'll does make a valid point is that the dog the Django dogs can be a little hard.
Mikey Ariel 12:51
I've tried many times. I think every time I run a duck sprint, at a Django event, I refund My, my knowledge of the Django Doc's structure. And every time I'm like, Oh, right. I remember this, you know, because I always, I always say, they know, if I'm new, and I want to get started, I get lost within about five minutes to so much of it. Yeah, I know, I know. This is I mean, that's the thing and about trying to restructure things, and that's information architecture. And that's a whole other can of worms. The point to answer your question, tutorials are an essential part of documentation. Right, especially if you have a big project with a lot of moving parts, and especially if it's easy to get lost in the references and the concept topics, right. So one of the main things for example, at Red Hat that we're doing is we're implementing use case based or story based documentation. Which is not exactly like tutorials, but it is it does serve a similar purpose where the procedure or the How do I use this software to achieve a goal or to solve a problem. And that's where the procedure based tutorial based end to end user story based, whatever you want to call it. The idea behind it is basically the same is I don't want to know what all the buttons in the cockpit do. Just tell me how to fly this plane.
Will Vincent 14:33
Right? Well, and I think Yeah, I like I like that section of your talk from Django con this year, which will link to where you you have not explained
Mikey Ariel 14:40
I will give credit again, this is from the director of content services started using it in his presentations when he tried to explain to the powers that be why we need more tech writers and better infrastructures. So this is this is definitely I didn't make this up, but I definitely Use it and I got permission for him to use it everywhere. Because I think it's a great analogy,
Will Vincent 15:04
right? Well, I think, what's the one thing I'm thinking about is, as someone who writes about programming for living is the other pieces I'm trying more and more to maybe it's part of use case, but to personalize my thing, so that I'm launching a dedicated Django site. And one of the first things I'm gonna do is ask, Are you a total beginner? Are you new to Django, but have experience with web development basically mimic what I would do in person where I just want to understand where the person is at. And from there I can customize, because I realized that I can, you know, I can do that if I ask one or two questions up front, I can just have a dramatically better experience for someone. But the the problem with most tutorials is that the person writing it is basically writing it for themselves. And they're assuming a level of knowledge and you know, you if it's a 10 page thing, you know, one page and if you miss miss a thing, you're just gone. And so it's all about the assumptions. So, anyways, I saw Yeah, I mean, that ties into the use case. But sort of knowing what the background is of the reader helps a lot, because a total beginner needs something different. And most documentation that I see is not written for beginners, which is why, and probably rightly so, you know, whether it's these billion dollar companies, they have tutorials, but they presume a level of knowledge that most or a lot of people don't have, but I guess ultimately, they're not their customers, which is why these billion dollar startups, you know, people ask me to write their docs for these companies. And I'm like, why is that? And it's like, oh, I think they just don't care about those people.
Mikey Ariel 16:32
Right? I mean, it's, you're absolutely right. And I see this in,
in smaller project, but most, but the problem is bigger in the, like you said, the heavyweight sort of doc sets and the heavyweight solutions. You know, I mean, for example, Red Hat is a beast. And we have like, dozens of products. Each one of them is complicated on its own, and then most of our customers basically buy subscriptions for multiple products. And I mean, we're at the level where, for a lot of things, you really do need a consultant, or a solution architect, and they actually write a lot of their own docs and we leverage them back into the dock set. But that's a different thing. I think that what you're describing is quite a common challenge. And one of the things that I talk about in my presentation, and also when I do some coaching is figure out your persona, you know, who are you writing for? And it might not even be a matter of beginner or advanced because, for example, I wouldn't necessarily you can make a certain set of assumptions, but even if, for example, you're writing, something for administrators, something for operator operators, something for, you know, people who are, I don't know, sis admins, all sorts of different people and roles who have a different foundation might approach What's your documentation looking for different things? So are you planning? I'm just curious, are you planning to do some kind of dynamic serving of docks based on those questions that people answer? Because that's something we're actually looking into red hat and a lot of other things where you have almost like a wizard, you know, or you checkboxes you're saying which products do I use? What's my knowledge level? What's my role in the company and then boom, you get right. Attack topics, which is really cool in theory, but a little bit hard to implement.
Will Vincent 18:33
Well, I'm, I'm yeah, I'm doing I'm sorry to interrupt. Yeah, I'm doing exactly that. I mean, so by the time this airs, I'm having a site learn Django con. It's just dedicated to Django and I think it's gonna be more that I realized, like, I already have a 50 tutorials. And when I one on one, talk to people, I suggest certain things, but I don't do that to someone who just comes to my site now. So I don't know. So you know, it'll be dynamic in the sense that I'll ask one or two Two questions and then point you on a roadmap. That makes sense.
Mikey Ariel 19:03
Great. And if you can do it in a way, for example, because one of the things that I found really frustrating was, if I go to the Django Doc's page, and I say, I want to start, what's the first tutorial or the first concept that I need to know? And you end up actually doing, getting into like this clicking rabbit hole, that very quickly derails you from the path. So if you're saying you have 50 tutorials, you know, it might be even, you know, something to consider is to chunk them according to stages. You know, as far as like learning curve is concerned. So yeah, someone is an absolute beginner you say you do this tutorial first. And then these three tutorials so like, actually really hold their hand more than what I find a lot of projects are doing right now.
Will Vincent 19:54
Yeah, absolutely. That's exactly what I'm doing. Which I mean, partly, I mean, this is being done in the you know, The email space everything is about personalization. And it makes sense, right? I mean, why just have one set of things for for everyone. So yeah, that should be that should be out in some form by the time this this airs. So that's, uh,
Mikey Ariel 20:12
that's great. Yeah, and I think I think in general is also indicates
the whole difference between, you know, tutorials or use case based documentation. And let's say the rest of the documentation, which is mainly concepts and reference right concept means Why do you use this software and references mean, you know, every single doc string or, you know, API references and things like that. And the thing about procedure based or use case based documentation is it should be opinionated, you know, and that's something that open source technology in general, and I've seen this in Django and Python and j. s and a lot of different projects, because a lot of the open source projects are documented by engineers. Who are used to working on specific components. And they have a little bit of blinders, you know. So it's, it's not like everybody works on their own piece, maybe there's an architect or a manager who oversees the big picture. But if everybody only documents their things, then you're gonna end up with a lot of specific reference documentation, but you're gonna see all the options. But they're not going to tell you which ones to use inside an end to end scenario where you want to deploy something, you know, so it's, it's a matter of like, taking it one abstraction layer above, and then figuring out you know, yes, this API can do anything you want. But which ones should I choose? That's the opinionated part of documentation that I think is missing from a lot of open source projects. And it's not necessarily because people don't care or they're doing it maliciously. It's just a requires a different set of skills to determine In this as well, and to talk to your users, like you're saying you're consulting, you know, you're asking these one or two questions in person, and then you're going to port it over to your website to do it automatically, which is already a great step that a lot of open source projects could use.
Will Vincent 22:16
What's more work, I think, is the issue. I mean, it's, that's what I see more and more.
Mikey Ariel 22:20
The automation question is always, you know, is it worth maintaining a system where you dynamically build documentation based on the specific snowflake use case of whoever's reading Don't leave me to do that you can
Carlton Gibson 22:33
have like a questionnaire that leads to a series of bucketed landing pages so if you are an absolute novice then you know his his five places to start if you are an advanced beginner where his five different ones, you know that that's not too hard to maintain, surely,
Mikey Ariel 22:50
no, it's not. And I think it's not too extreme. I think any extreme in this sense is probably not a great idea. And the tricky part But I think the most useful part is to try and balance. You know, if you're saying I want to be more opinionated and give you more specific documentation, there's only so much you can go, you know, there's only so far you can go because even, for example, at Red Hat, we have, you know, we're trying to be more opinionated, but we have to look at the, for example, the top three use cases, right? We can't document every single corner case. And that's something that we also need to give credit and trust in our users. So for example, if we say we recommend that you do things in this way, there's nothing stopping you from, you know, adding a few links of saying there are a couple other ways to do it. If you don't like this or if it doesn't work for you. You can't predict everyone's specific use case, but you can try and work towards compiling low Learning Resources, right? Because that's basically what documentation is, is to help you learn how to use the software. And so you should figure out how do you want people to use your software and try to direct them to that. Or if they want to learn how to code and they want to become contributors, then there's a different learning paths for that as well. And they should focus on different content.
Carlton Gibson 24:23
Yeah, it does. It does. I'm sitting here thinking and just sort of listening to you to have your talk and thinking about how all this relates to the Django project because we have a massive docs and for instance, a contributor guide, that's like 6000 words long and people find that quite intimidating and people find you people come to the homepage and the homepage, isn't that clear on what you know, exactly, as you said, You've got to click around a bit to find even the tutorials. Yeah. And then I'm thinking about the, you know, the, the contributors, I'm thinking, Well, you know, you're right, these are different skills, and we have lots of people coding up stuff on the ORM, but they're not necessarily the best equipped to, you know, improve the docks. And it's just a massive challenge. I think it's
Mikey Ariel 25:03
Yes, it's a big project. And the bigger the project gets, the harder it is to chunk information in a way that it won't get over compartmentalised. Right, because that's that's kind of what happens with a lot of big objects. So you're not alone in this. And I don't know currently, if you might be able to, you might want to edit this out if I'm not supposed to talk about it. But we did have a conversation. Yes. With Russell, about getting some help. Documentation site to the Django project. Yes, no, and this is something we should talk about. This
Carlton Gibson 25:38
is something that, I think is a really good idea. We've got fellows. I think we can talk about this. I think this is, you know, not just an idea. It's a good idea. But we've got a couple of fellows who and we work on ticket triage and we work on you know, all sorts of things. I wonder if it would be possible and it might you know, I've got a check about the DSS nonprofit status and all the rest because it's there are limits on What you can do, for instance, Merritt Maris and I were, we're not, we're not contracted to code on Django, we're contracted to work as community managers almost imagine he managed the issue tracker and resolve issues like that and do the releases. But coding isn't something which a nonprofit is allowed to pay for, because software development doesn't fit according to US tax laws, which is fair enough. So I just I need to check about the writing but one idea was could we get a doc smell? You know, does the does the DSF have capacity to bring someone in maybe part time or full time to work on the docks because we have these kind of information architecture issues that we talked about, but also we've got over 1000 dogs tickets that you know, it's not that they're necessarily that hard per se, but they need love and care and attention and somebody with, you know, the written English skills because a lot of our contributors English isn't their first language. So, you know,
Will Vincent 26:54
but sometimes they're better
Carlton Gibson 26:56
writers. Oh, yeah. No, like there are some non plain you've contributed who's second first language isn't English you have better English than I do, by, you know, a country mile. But did I tell you
Mikey Ariel 27:07
a secret? English is not my first language?
Most it's almost that I'm from Israel. Yeah, so I grew up with English at home, because my father spent some time in the States when he was young. And then when I was 16, we moved to California. So I lived there for five years. But English is almost my first language. It's just a just a very close runner up. But there is actually an advantage just beside segue. There is an advantage sometimes learning English as a second language, because by the time I got to the States, I actually wrote better essays than some of my native born classmates because you study it much more structured way.
Unknown Speaker 27:49
So without
Mikey Ariel 27:51
my a much more formal and unstructured way, but I want to I want to comment a little bit about the docs fellow idea because I think You asked about the Django project specifically. And this is something I kind of try to plant the seeds as we go along, I think looking at the documentation and looking at the ticketing system, the the challenge is bigger than just getting drive by contributors. And I think Django project could really use even as a short term contract. You know, I mean, if I was in a different place in life, and I would, for example, be able to dedicate myself to doing the information architecture, tackling and, you know, figuring out how to triage, you know, dock tickets and stuff, it's, it's even, it might be enough to just get someone for a few months, as a as a contractor to just say, here's our documentation set. Please knock yourself out. Give us a proposal on how to restructure it, clean it up. It's better if you get someone who's not directly involved, for example, with coding or someone who has a bit more of an objective perspective, and is not emotionally attached to what you've done until now. So that might be something to consider there. And I think it's, you know, for some projects, the problem gets too big to tackle, you know, with volunteers. And that's, you know, that's something Russell also talks about skills cost money, you know, just like you would need to pay a lawyer or community manager to do things that are not software development. I mean, if you can get, you know, approval for a doc speller, I think it would be really beneficial because you can get a lot done in a short amount of time. And then they can also set some contribution guidelines, you know, content to help people, future people, they might even might even be able to do training, you know, webinars or presentations or Write tutorials on how to get the basics, you know, for your, for your contributors, anything you can do to help people onboard onto the project would be useful.
Carlton Gibson 30:10
Yeah, no, I think I think it's a good idea. And obviously what happened after Django con Europe is we talked about it and then you know, the day to day took over, and it's been on the back burner, but
Unknown Speaker 30:20
I think,
Carlton Gibson 30:23
you know, there's obviously the ORM and the admin, which are big issues in Django, but then the next the next, the next group of open tickets, we have documentation tickets, and you know, exactly as you talked about the front pages and gray and I, I see it as just a mess. I think it's okay to say it's okay. It's okay. No, I mean, look, don't get me wrong, it's about the document. The loads of efforts gone in, it's all good stuff. But the reality is, we find, we find that there is barriers to participation. We have people who like I just couldn't get started contributing insight, but it's not that hard.
Mikey Ariel 30:57
Yes. Because it's, it's it's there's a Difference between, you know, making the front page look nice. But once you start getting in, I mean, it's still a beast. And it's very easy to get lost not because necessarily something is written badly. It's just the project really is that big. And a lot of people I've met in the Django community who remember what it was like when things started, it's almost like it's hard to believe that the project is so big that new people can get lost. And that is a factor of psychology that a lot of projects don't realize, is a factor. And this is part of the justification I say, or something like that to bring in a fresh perspective. Because if you're getting someone an act like someone who's an expert in their field, giving an opinion, or analyzing where you're at, they don't have all the history in their heads. Right And I mean, a lot of pressure objects that I do consulting for. They say, Oh, you know, we started out, we just had to read me. You know, six months later, we have like, 50 topics, and we don't know how to organize them. And, you know, even just that kind of jump, you know, can be disorienting. And a lot of people will just say, Well, I just I just don't want to look at it. You know, I'm just gonna hope the problem will go away. But documentation is not going to organize itself. And I don't know what the state. Yeah, I don't know what the state of the doc tickets is at the moment. But the last time when I was in Django con, I had a chat with somebody about it. And they said, the problem is that a lot of those documentation tickets are actually not low hanging fruit. Yeah, so it can you can have, let's say one ticket, but it hides inside a really big feature or a whole section of the project. You know, so could theoretically imply that the ticket management itself could use a fresh look. Because for example, I don't remember if you break down coding tickets in, according to like epics or stories or something like that, like if you have a big feature, do you create sub tickets or subtasks? You know, for the different components. This is this might be something that documentation tickets can benefit from Yes, because you can say, oh, document the RM, right. But that's, that's
Carlton Gibson 33:37
a huge, there's no possible way to put
Mikey Ariel 33:38
in one ticket, you know, so it could be that people are looking at those tickets. And a, they might be not written in a helpful way. It could just be, you know, document this thing and it doesn't actually have a kind of breakdown of what needs to be documented. It could be that the tickets are hiding inside really big tasks. And it's worth breaking them down, I think most of it is
Carlton Gibson 34:02
that it's at this stage because Django is very mature. And because the features are mature and the ORM is mature, if there's a documentation issue on the ORM, it's not that something's not documented. The issue is that it's this really particular key use case, which is needs to be clarified in the documentation. And it requires quite a high level of understanding in order to be able to resolve that ticket because you've got to really understand the code, and then you can and then you've got to have the ability to phrase it in the clearest English and
Mikey Ariel 34:35
Are you sure that you really have to understand the code? Because I'll tell you why I'm asking. Because one of the advantages of, for example, me being a tech writer, but not being a coder is again, I'm not emotionally attached to the code itself. And especially if you're talking about a specific use case that needs to be documented, it usually involves more than one component and It usually involves having to, like, use multiple things in order to achieve a goal. And it requires a different style of thinking. Yeah, so the fact that I can't write code I can, I learned how to read code enough, just enough to understand what I'm looking at. Which helps me but I also communicate and actually have conversations with the engineers. If I need to, I work from specs, I work from a lot of different types of information. And if you're looking at a dock ticket that's that requests to document something specific, then maybe it's better if you are not an expert in or that you didn't write this specific component or something like that.
Will Vincent 35:52
Yeah, well, I think there's really something to that because I was gonna ask you Mikey, how do you how do you deal with you maintaining your empathy for them? The first time or for who you're writing for, right when, like with Red Hat, you are much more aware of Red Hat itself than you were a couple years ago. And therefore, I think it's hard to have that same beginner's mindset about it. But perhaps when you don't day to day code, you maintain that more, because certainly I have that challenge with Django, right as my own comfort changes. It's
Mikey Ariel 36:22
your cup, I can work hard, right? So you remember when when people when people arrive at your documentation set or when people arrived at your software project, they are not in their comfort zone, they're learning. So even if they're very comfortable in something else, then you're then then they're starting out from a different place. And I think that even though I am more Linux savvy and more Python savvy, because OpenStack is written in Python. And I think that the fact that I've maintained a little bit of a distance From the code itself, allows me to get to keep that fresh perspective, and specifically in OpenStack, but actually in a lot of our products, there's so many components. I'm actually not even in charge of documenting the whole set of OpenStack components. I'm only in charge of certain product areas. For example, in my case, it's the virtual compute in high availability. Somebody else in our writing team is in charge of networking. Somebody else is in charge of storage, so and there's always something new happening. So almost every feature or user story that I document that comes in, I'm learning it from scratch. So I'm getting introduced to it from a fresh perspective. And so that kind of helps me keep a little bit of that big picture in mind. But not but not get so far in the weeds.
That I lose track of that.
Will Vincent 38:03
What and how do you this is a question I have. How do you avoid writing just like a recipe list for something, or maybe that's fine professionally for you. Like when I'm writing a book, The challenge for me is to not just say do this, do this, do this, do this and then predict, you know, some in person, people make mistakes, there's a back and forth, but in writing, I want to let the person know that I'm with them, like he probably make this mistake here and there. But it ultimately is a bit of a, this, this, this, this this. And so maybe the writer in me kind of gets frustrated that format. Does that. Is that something you think about? Or is it fine to just have like a recipe list for a particular feature?
Mikey Ariel 38:44
I'm gonna use the classic answer of it depends. Every
Will Vincent 38:54
Friday, we always try to be opinionated. But you know, some things it does depend. It
Mikey Ariel 38:58
depends. So here's the thing When I first started learning tech writing, I got a great piece of advice where you have to keep the language level at fourth grade level American English, right? So present simple keyword sentence structure. Super simple. So this is advice that I got for working on enterprise documenting. No,
Will Vincent 39:21
I believe the advice Yeah,
Mikey Ariel 39:24
yeah. So the concepts, and the subject that you're describing in your documentation is already pretty complicated. So what I try to keep in mind is to make the language flow as simple as possible, so that people won't get disoriented by being too verbose. That being said, the reason I said it depends, is because some for example, if you take the Django girls tutorial, okay, which is a beautiful example of Very sweet and has fluffy language. And it's personal, you know it, it uses a lot of really positive superlatives. Why? Because it is meant to help women take their first step into the great unknown of programming. And these are people who have a lot of anxiety, or people who need to have that personal tone. Okay, so if you're talking about the tone of the documentation, for most, for the most part in the bigger, you know, enterprise e or, you know, software projects that are aimed at, let's say, the general tech population, okay, developers, administrators, things like that. You should consider your audience they don't need to have, you know, fluffy confirmation bubbles about everything. And for example, if you're talking about a procedure, you know, you say no This should be the output. If the process was successful. If you get this error, you know, or if you get an error, you know, this is how to troubleshoot it. So that's the information can still be there. But most of the time, it's better to keep the language as dry as possible, especially for the bigger documentation sets. Because, for example, in OpenStack, we have 12 writers. And the whole documentation said should read like it was written by the same person. So we have style guides, and we try to keep the language as clean as possible. It also helps prepare for translation, because the easier it is to read, linguistically the easier to translate, but I wouldn't need to do that, for example, in the Django girls tutorial, because I want to be fluffy. I want to be happy. I want to get people at ease, and I'm using a more personal tone to achieve that goal. So,
Will Vincent 42:01
right I like that one part of it too is the, I mean, I joke with some of my friends happy path programming, where you just say, if you like a watch a video, video tutorial and someone just, you know, if I make no mistakes, I can do something complicated quite quickly, but it doesn't. Yeah, having those asides, which you sort of referenced are important to, you know, aside from tone to say, here are probably some common mistakes you will make, and don't, you know, just don't become discouraged if you make them because you're gonna make them because I made them writing this tutorial. And presumably, I know something.
Mikey Ariel 42:34
Right. And I think is for for independent folks or people who are involved with open source projects when you write tutorials, especially for beginners. There's definitely space for positive reinforcements and validation. And, for example, what we do, sometimes we'll say, instead of saying you might have this problem If so here's to troubleshoot, we can say make sure you put in this variable in this format, otherwise, it's gonna fail. You know, so we tried to kind of help them get the foundation as they go. And sometimes you'll have a procedure where every other step has a note, you know, saying make sure to do it like this. I'm not sure if that's the best way to do it like that. But, you know, there are different ways to kind of try to channel the user to towards the right path. On the other hand, I have to say that, you know, and I think I talked about this in my talk, because sometimes people don't believe you. And they'll try to use your software out of scope. And then when it breaks, then they're saying, oh, okay, well, I should have done what they actually said.
Will Vincent 43:51
Well, Carlton, it's like our kids, right? I try to stifle the urge to say I told you so but I'm definitely thinking it when stuff like that happen. Well,
Carlton Gibson 43:56
you know, children will be children.
Will Vincent 44:00
Write you have to you can't I can tell you the right way to do it and what mistakes you will make. But until you do it, which you will you won't hear me. And then you'll
Carlton Gibson 44:06
say, well, you're too late for minor very much like, because you told me I'm doing it the other way.
Will Vincent 44:11
Oh, of course. Yeah. Well, it comes in phases. Yeah, the defiance comes in waves. So
Mikey Ariel 44:18
I know adults who are like that as well. It's not just the kid.
Will Vincent 44:22
Yeah, well, I know. We're sort of coming up on time. One thing. My last question, then, Carlton, I feel like I've dominated the discussion is I wanted to ask you about some opinions versus best practices. And maybe this is, you know, so if someone's if there is a Django, fellow on writing, it's probably hard for Django itself to do that. But for me with my writing, I see more and more the patterns in Django for example, Carlton, I had a podcast on How's it feel when you work with something for a while you see the patterns. And so for example, I always try to call out, this is something you know, there's these splits in the road, you know, so, project structure, there's, you know, a couple ways to do it. I will say you Just need to pick one. And it doesn't really matter. Or if there is something where there is, I think a best practice, I will say, here are the three ways people do it. And this is why I advocate for this one, but kind of have these call outs of like, you know, you'll see it done different ways. And either it matters or it doesn't matter. That's something that I, I think a lot about it, it'd be interesting. I don't know if you could do that in the docs, right, Carlton to say like, for example, like the doc say, you should use a custom user model, but it buries that maybe it should say that up front. Whereas should you have a period after star project or not? What not? Yeah, and even custom user model, it's like, well, you could have the user profile, right? It's not like where's the space for the discussion, which is really what this podcast is about is having the discussion rather than just a list of things,
Mikey Ariel 45:45
if that makes sense. And it's a good question to ask because that's kind of throwing back to the when I was talking about balance between between being too specific and too broad. So for example, if you Have a fork in the road? Where does the road begin? And where does it end? Right? Because if you're structuring, for example, you know, a project in Django, there's a lot of different components and they all need to work together in different ways. Do you do something out of the box? Or do you use let's say, a custom? Or do you customize the component, right? So this can be something that you can direct them within a tutorial, or you know, you want to think about the end goal because it's it's very rare that you just have one fork in the road. And
Will Vincent 46:37
oh, no, it's a choose your own adventure. Yeah.
Mikey Ariel 46:39
Yes, exactly. Exactly. So how do you help people choose their own adventure? Right. Although in Choose Your Own Adventure books, the ending is usually there's only like, maybe one or a few different endings you can have. This is a it's a big question. I mean, it's a big question, and I think that So some solutions I've seen, for example, actually recently worked on some topic where we did an installation procedure that was divided to a few subsections. Right. So you have, you know, like the under cloud, the over cloud, and then the guest instances, which is how the, the stack is compiled. So we said, if you're doing a fresh install, do everything on this topic from start to finish. And then right before before we even started going into the procedures, we said, if you are starting from a pre deployed under cloud, which is the foundation, you can skip these and go straight to here, you know, so so you can have, it depends on on what you're trying to achieve. But sometimes it's good to have everything documented from start to finish and and say, you can skip this, but it's usually better. And I'm going to give this advice in general, when whenever a user opens a documentation Topic whether it's in the web browser, well, I'm thinking it's a web browser. Because that's how usually things go. It's usually better to have things self contained. Instead of, for example, if you get to step two, and then you're saying, well, there are two options of doing this, you can either do option A or Option B. And every option, for example, is a link to a difference. That's dangerous, because as soon as you're sending them away from the topic, then you're making it much harder for them to keep the context of the full procedure. So I think before you even look at the forks in the road, see what the end goal should be. And if you want them to get to that goal, you're going to need to figure out how to explain things in a way that's self contained within that, let's say tutorial or procedure. Yeah, yeah, it might be better to break it down to multiple procedures depending on how common the use cases right
Carlton Gibson 48:58
don't give a give. opinionated route. And then but in sort of side boxes, say, and you could do this at this point, but come back to that. Exactly,
Mikey Ariel 49:06
exactly. Yeah, that's what I that's what I do. As an aside. Yeah, as the person who's creating the documentation, you are already considered the expert from the readers perspective, so what you might think is an opinion, they see as a best practice. So that's something that you need to keep in mind is kind of scary thing. Well, it is it with great power comes great responsibility. You know, that's, that's something that we need to keep in mind. Because for example, when we document things, it means we support them, right? So if you're documenting how to do something, and you recommend people how to do something, you should consider the fact that they'll actually do what you suggest. And so you want to make sure that if they do that they get to where they want to go.
Will Vincent 49:55
Yeah, I think I like that. As we said the address Something but maybe saying, you know, as an aside, or you know, you could do this, but I'm not going to get into it and providing an opinion. So, I mean, I think one of the one of the best teachers I ever had would, was actually for accounting in business school, he would answer every single question that people asked, but this was a class of like beginners and CPAs. And but he would say, this is relevant to what we're talking about, or it is not, right. So you could turn your brain on and off instead of becoming overwhelmed. And so I think of that in terms of writing of like, you know, yeah, I may mention these things, but this isn't the time or space to get into it, which is, I think, the point you were making.
Mikey Ariel 50:33
Exactly, exactly. So you know, telling users which information they need to focus on at this point, right is reading one shell to the process, you know, especially if you're talking about such a big project like Django, I want to achieve a certain goal using Django software, you know, tools, just give me like, you know, it's just barely good enough, just barely documented enough for what I need to achieve. You can have links and and sections, for example at the end or maybe as a note saying, if you want to read more about this or dive into it more go to this topic, but you need to explain it very clearly, this is not necessary, right? It's an optional or l alternative to what I'm giving you right now. So people can choose whether or not they click that link and go to another topic and get a bunch of reference information or concept information. Because a concept information, for example, can be Why would I use Why would I go to this part, this fork or this fork, right? And so you need to assume that if people are doing the procedure, either they've already made that decision, or they're not aware of that. But they trust you to tell them what's the most recommended way to achieve this goal. But you can also give them side links and make sure that it doesn't distract them. From what they're actually trying to do,
Will Vincent 52:02
yeah, well, I think I mean, Carlton, when you were consultant, I found when I was consulting the challenge of something like this is, someone will say, I want to achieve x. And you say, Okay, I suggest this. I suggest why based on all my experience, and then if they want to get into the weeds, it's like, Well, okay, we could really get into that. But that's like a novel when I just gave you the,
Carlton Gibson 52:23
I mean, there's one thing I found with like people, you know, clients who would be hiring you, you have the expertise up there to build the thing, and they'd ask for a solution. So they define the problem right there, the client, they tell you what to build. And then you come in as the quote unquote, expert, and then they say, oh, but why aren't you using this? or Why aren't you implementing this way? It's like, no, don't give me implementation details. That's what you're paying me for.
Mikey Ariel 52:47
Why exactly, and this is something that I can also see that is very relevant to documentation because you're basically coming in as the expert and especially if you're doing tutorials, It's basically it's very similar to solution based documentation, right, which is how do I use all these different components to solve my problem. And so if you're, you know, looking at it in the similar way that you would look at a consulting engagement, just think that you're consulting to the most common use cases. So let's say you have 100 customers instead of just one, and they all want to achieve roughly the same goal. So there's nothing there. You shouldn't worry about appearing, you know, trying to get people not to get distracted into the
Carlton Gibson 53:39
weeds, you know, and you In fact, you're doing them a disservice by over complicating the story.
Mikey Ariel 53:45
Yes, well, let's just say that it's very rarely a tools problem, right? And that's the psychological part that that I keep mentioning, when people ask me this is you got to talk to people you got to communicate and they have to communicate with If you, you know, so for example, somebody says, I just want to know how to use this, you need to say that's not specific enough, you know? Or if people are saying, why don't you use this, you know, this component or that solution, you know, if they want to get into the implementation details, a lot of times, you might find that easing their mind about the details might help them accept or adopt the overall solution that you're proposing. You
Carlton Gibson 54:34
see, a lot of times they just want in that particular circumstance, they just want you to justify your choice. So that they know to trust you. That's Yeah.
Mikey Ariel 54:44
That's a conversation that needs to happen. Absolutely. As long as they're not being malicious, or especially trollee about it, then you should be able to do that. I mean, when I interview engineers about documentation, you know, I'm always you know, asking Questions to possibly that. And sometimes it happens that we uncover gaps in what they've initially explained to me that they thought was enough. But if I'm pretending to be a first time user, asking all the annoying questions, it helps to bounce those ideas off of another person and get feedback, right? So it's the basic concept of feedback. you propose a solution, whether it's with documentation, or in your consulting engagement, you know, or in your workshop, that you give it a conference. And it is expected and encouraged that people will not necessarily challenge but try to understand and everybody learns in different ways. So people might ask you different questions. Exactly.
Carlton Gibson 55:46
So we did two workshops I did getting contributed to Django sprinter at Django con us this year. And you know, we got the skirt gang Started Guide but going through it with 40 people we found, you know, The issues, it was amazing because they be having in this massive group, they're going through it, they were questioning the, the steps and they were hitting the errors. And it was, you know, we got a good list of improvements. It was super, which is
Mikey Ariel 56:13
great. I mean, when when I hear you're taking me back now to my first Django girls workshop, the first one that was at Euro python 2014. And because they made the tutorial, and then they ran the workshop with the first set of 45 participants, and at the end of the workshop. Well, during the workshop, of course, we discovered all the bugs in the tutorial. And so naturally being a tech writer, I said, Hey, why don't we do a doc sprint, you know, during the Sprint's at the end of the conference and fix the tutorial. So we actually got the Django girls participants who just made their first website ever to also make their first documentation contributions ever. So I don't know if you will have a chance to do that. But maybe that's That's also an exercise that can really help if you create a new set of Doc's, especially tutorials, if you get people to test them, and then help you fix them and make them better. It also means you don't have to do it alone, you know, something I really like to engage, engage the first time users in feedback in an active way. So they can actually submit the ticket and make a pull request, you know, because the idea is fresh still in their heads because they've just done this tutorial. Right. So that could be a nice exercise.
Carlton Gibson 57:33
And there's something so good about the Django girls process. They put workshops in there putting so many people through it, and yet they seem to have what I'd really like is some way of engaging some of those and getting them contributing to open source or joining in in open source projects in some way.
Because it
feels like there's a big gap between what's next what's after that.
Mikey Ariel 57:54
Yes, well, in the beginning, I remember we had some trouble because a lot of people were lost afterwards and they were like, I don't know what to do. With this newfound knowledge, but slowly over the years, and what I like is happening right now is a lot of companies are actually collaborating with Django girls project to hire out junior level engineers or programmers from the alumni. You know, so the the secret was to collaborate with, with open source companies, outsourcing companies, whatever company is consulting, to be able to continue the training. So and that's, again, it's a human factor and it's collaboration. But I think getting people to practice is probably the most helpful thing. You know, there's no substitute for, we say stage time in theater or you can say flight hours. You know,
Will Vincent 58:46
right. I think it's guided practice, right is what really is you what people need when they're starting out. And I mean,
Mikey Ariel 58:53
church practice, maybe not right, which is hard to be there with them, but give them feedback into iteration,
Will Vincent 58:59
right or even Just do this next. I mean like so this this site which we learn Django calm I mean, you know, being not wedded to the book format, it will have, for example, like use Django to build a clone of five different popular apps where they can see everything is crud, but until you've built, you know, your Facebook, your Instagram, your Twitter clone, you don't see that, but then it's like, oh, now I have these clones or deep dives. I think that's the challenge is like Django admin. There's so many things you could do, but like, I've, I'm gonna have a deep dive where it's like, let's just have a project and let's just blast it out with all the things we could do. That's to me easier than reading all the docs, which is more of a table of contents rather than a guide.
Mikey Ariel 59:41
Sorry, I keep cutting you off. I get excited.
Will Vincent 59:44
I'm the same way. I mean, Carlson barely gets a word in this pod. I can empathize.
Mikey Ariel 59:50
Yeah, I totally get it. And it's something that's really useful. And one of the things we tried to do, for example, at Red Hat is is really give a lot of code Examples give a lot of as close to real life implementations as possible. Because if you get people practicing, doing the thing, rather than learning about how the thing works, then they'll get more practice at actually building something and one of the great things, you know, with Django girls, for example, is it takes you really from the ground up, you know, you learn get, you learn how to, you know, structure your folders, you learn how to set up your sync with the remote with a hosting server, like all the you know, even installing Python, you know, is something dependencies, you know, all these different things that, you know, if I just read about Python or Django, go, I would really get lost before I even knew what to do first.
Carlton Gibson 1:00:54
Totally agree, Carlton. Is there anything you want no dog, no head out, you know? Again, just constantly Just thinking about all that being said, in you know, I always get really blown away whenever I talk to Mike you know, it's just like Yeah. Because it's such an it's such a in this. Remember the literate programming thing is Donald Knuth had this idea that you could write this beautiful book and code in programming and execute build executable code in the same thing. In the same artifact, yeah.
Mikey Ariel 1:01:23
It's a lovely dream.
Carlton Gibson 1:01:24
Yeah. But you're asking people to be the world's best programmers and the world's best writers at the same time. And it's, it's just not the reality that we're in. So for me exactly
Mikey Ariel 1:01:32
in the Django community is actually collaborate. Yeah, exactly.
Carlton Gibson 1:01:36
And in the Django community, we got all these people who do fit that exact profile that you've talked about, they might be English majors, or they might be, you know, wordsmith or whatever. They just happen to be using Django as well. And it's like, for me as the Django fellow. It's like, how can I? How can I lay the breadcrumbs out to entice those people to come and join me?
Mikey Ariel 1:01:54
Exactly in a similar way that you have the Django fellow they take care of, you know, triage and Release Management, all of that sort of a project architecture thing, which actually enables the, the programmers to do their jobs because they don't have to think about it. So in a similar way, for example, we can have a content strategist, you know, or even a program manager or whatever you want to call it a fellow, you know, information architects, you know, that's just naming things is hard, but the function of that person will be to give to enable writing contributions to come in more easily, because they can prioritize the tickets, they can break down big monster tickets to sub tickets, they can decide, together with, you know, the body of people who decide which features are coming in, to also decide which features should be documented. So it's kind of like having a product manager for documentation. Right. So But, but a lot of the roles from the engineering world from the programming world can be, and are actually ported over to the writing world. And so if you have all these wonderful, linguistically inclined people, but they're not information architects, right, so if you give them a task to write something, they can do it. But how do they decide which ones to take? What's more important? How far Should I document this? Should I just do it an overview? Should I get really deep into it? These are all things that you I mean, you can't expect the programmers to decide these things. This is something that needs to be a community. Maybe consensus based or however you accept ever you make the decisions about what to code can also apply to making decisions on what to write.
Carlton Gibson 1:03:47
Yeah, no, it makes sense. It's,
Will Vincent 1:03:50
as I say, blown away. Well, once we get that once I get that merge shop set up for Django, which Django girls has done a good job of, then we can maybe make it easier to fund that. position. Great. Well, thank you so much for joining us. So your personal site is dark side of the moon, is there anything else you want to call out if folks want to get in touch with you?
Mikey Ariel 1:04:09
Well, thank you so much for having me. I'm really happy that we could do this. I'm always happy to geek out about docs. And I do love the Django project. So I'm really happy that we get to do this. So yeah, Doc Side of the Moon calm, or you can follow me on Twitter. I am that Doc's lady on Twitter, GitHub and IRC freenode. And please follow write the docs. We have conferences in Portland, Oregon, and Prague in the Czech Republic where I live in Australia. We're also looking to do an East Coast Conference next year. All of our conferences are small enough to have a lot of Pac man's. And we have a lot of meetups, we have a slack team. And we're just a really friendly community and we welcome people from all roles. So if you're a writer, if you're a developer, if you're commuting Any manager, if you're a designer, if you're a librarian, support engineer, we love everyone. And we do believe in collaboration. So if you're a developer, you don't have to retrain as a technical writer to create documentation. You just have to find the right people to work with super.
Carlton Gibson 1:05:18
Well. Thank you, Mikey. That was just amazing to have you on.
Mikey Ariel 1:05:21
Okay, wonderful. Have a great one, guys. Okay.