Transcript: Technical Writing - Mikey Ariel

I'm Will Vincent, joined by Carlton Gibson.

Hi, Carlton.

Hello, Will.

Hi, Mikey.

Hi.

Will?

Hello.

Mikey.

What are you doing today in terms of uh helping developers write better technical docs?

Uh so I'm a senior technical writer at Red Hat and I work on OpenStack platform.

And uh the other thing, uh the main thing that I do is I'm also on the core operations team, global core operations team, uh at Write the Docs.

So we organize conferences, meetups, we have online spaces for anyone who cares about documentation, content, communication, and so on, mainly in the software industry.

Because that came out of Read the Docs.

And can you tell me the history and the relationship there?

So the co-founder of Write the Docs is also the co-founder of Read the Docs.

So Eric Holscher uh is the person who started basically both uh 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 um with a different team.

So he basically has two projects or ventures.

At conferences.

This is one of the traditions we have at Write the Docs, uh, 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 uh conferences or a bunch of people who don't know each other who get together.

Yeah, so we

We do that, yeah.

You can tell us all about it, but we do that at 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.

Uh that's great to hear that you're doing it in Django uh conferences as well.

Uh Pac-Man rule is basically a social helper uh where if you're standing in a group with, you know, two or three more people, uh 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 a conversation.

So it's basically saying you can do this and don't be afraid to join a group and meet new people.

So that's cool.

Um, or or are there standards 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 what are the how does one get into technical writing?

Um, 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 uh 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 uh profession.

As soon as developers realize that they have to document what they're um 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.

Um, but uh generally up until recent years, if you wanted to be a tech writer, uh there hasn't really been a strict university program.

Somebody might learn a technical writing course as part of computer science degrees.

Um, but what actually happens is people who are drawn to the tech industry, but who have a strong linguistic background, um, a lot of uh tech journalists, uh people who um 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 uh before I was working in tech writing, um I was working in television.

I was uh doing production management, I was doing video editing, I was doing, I was working all kinds of administrative things around uh the broadcast industry, which was another passion of mine.

Um, but I basically went by the route of a private sort of placement company uh that they basically outsourced 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.

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 um skill.

Yeah, uh, because that's the part that really makes the difference between, let's say, technical writer and uh developer, right?

Because we deal with words.

Right.

Uh that's the main thing.

Like you you kind of implied that that was true.

Self-documented code is code you wrote recently.

That's my that's one of my favorite controversial things to say.

Yeah.

Well, I think that in general, it's not necessarily see, that's the thing, right?

Uh, 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, let's say, 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 um 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 those are all things that should be documented even if you don't document every single function in detail.

You need you need a decent introduction, right?

You need a decent Git um readme, or you need a a tutorial or getting started, or

Exactly.

And if your users are developers, you still look at them as users because they use what you've 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.

Well, marketing's another thing that I think developers are famously bad at.

So yeah,

They didn't specialize in it.

This is one of the things that um that I always try to diffuse a bit of anxiety or resistance when I talk to some developers because they say, Oh, I'm I'm terrible at documenting, I should I'll never do it.

It's like the uh the equivalent of like, I'm not technical.

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, um C sharp, but I used IDEs for all my doc strings, and you know, I never really worked in a terminal, but I had a good uh foundation as a technical writer, and I had the open-mindedness to learn new things, and uh 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 um, but the the thing, the reason I mention this uh anxiety or resistance is that a lot of times developers um 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.

Um, 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 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.

Or do you think there's a distinction?

And I'll 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 docs and other docs weren't tutorials, but now with experience I see I see that 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.

I think I I've been a technical writer for 10 years, and maybe a few years after I started, um there came a huge wave of uh 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 gonna 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?

Um, so but Django Project treats it like the documentation.

So it's actually misclassified, or the the the term is not the most accurate.

We do have topics and tutorials and reference in different sections, and you know, there's the how-tos and there, you know, there are there have been historical attempts to break this divide, but I think Will does make a valid point is that the doc the Django docs can be a little hard.

Um I've tried many times.

And every time I'm like, oh right, I remember this.

You know, uh because I always I always say, you know, if I'm new and I want to get started, I get lost within about five or yeah.

I know, I know.

But this is, I mean, that's the thing in uh about trying to um restructure things, and that's information architecture, and that's a whole other can of worms.

The 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 uh we're implementing um 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.

Well, and I think, yeah, I like I like that section of your talk uh from DjangoCon this year, which we'll link to where you you had that plane cockpit.

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 infrastructure.

So this is this is definitely I didn't make this up, but I definitely use it and I got permission from him to use it everywhere because I think it's a great analogy.

Well, I think uh what's the one thing I'm thinking about is as someone who writes about programming for a living, is the other pieces I'm trying more and more to maybe it's part of use case, but to personalize my things 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 realize 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 uh experience for someone.

But the chal 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 ten-page thing, you know, one page in, if you miss us miss a thing, you're just gone.

And so it's all about the assumptions.

Right.

Uh so I anyways, I so I yeah, maybe that ties into the use base, but sort of knowing what the background is of the reader helps a lot because uh a total beginner needs something different, and most uh 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 the 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.

I mean, it's you're absolutely right.

And you I see this in um uh in smaller projects, but most but a but uh the the problem is bigger in the the like you said, the heavyweight sort of dock set 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 docset, but that's a different thing.

I think that uh what you're describing is quite um uh a common uh challenge.

Uh and one of the things that I do 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 um you can make a certain set of assumptions, but even if, for example, you're writing something for administrators, something for operators, operators, um, something for, you know, people who are, I don't know, sysadmins, all sorts of different people and roles who have a different foundation might approach your documentation looking for

different things.

Um, so are you planning?

I'm just curious, are you planning to do some kind of dynamic serving of docs based on those questions that people answer?

Because that's something we're actually looking into at Red Hat and a lot of other things, where you have almost like a wizard, you know, or you do check boxes, 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 a tad set of topics, which is really cool in theory, but a little bit hard to implement.

Yeah, I mean, I'm doing exactly that.

I mean, so by the time this airs, I'm having a site, learnjango.com, that's just dedicated to Django.

And I think it's gonna be more that I realize 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 it'll be dynamic in the sense that I'll ask one or two questions and then point you on a roadmap that makes sense.

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 docs 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 uh, you know, something to consider is to chunk them according to stages, you know, as far as like learning curve is concerned.

So if someone is an absolute beginner, you say you do this tutorial first, and then these three tutorials.

So like actually really hold their hand um more than what I find a lot of projects uh are doing right now.

That's uh 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 uh it makes sense, right?

I mean, why just have one set of things for for everyone?

Uh so yeah, that should be that should be out in some form by the time this this airs.

So that's a

oh that's great.

Concepts 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, in Python, and JS 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 uh specific reference documentation, but uh you're gonna see all the options, but they're not gonna 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 it requires a different set of skills to determine 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 gonna 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.

I mean, it's uh that's what I see more and more

You can have like um a a a questionnaire that leads to a s a um a series of um bucketed landing pages.

So if you are an absolute novice, then you know, here's here's five places to start.

If you are an in you know advanced beginner, well, here's five different ones, you know, that that's not too hard to maintain, surely.

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, um, 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.

Um you can't predict everyone's specific use case, but you can try and work towards um compiling uh 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 uh become contributors, then there's a different learning path for that as well, and they should focus on different content.

It does.

I'm sitting here thinking, I'm just listening sort of listening to you the two of you talk and thinking about how all this relates to the Django project because we we have a mass of docs and, for instance, a contributor guide that's like 6,000 words long, and people find that quite intimidating, and people find you know 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 docs, and uh it's just a massive challenge, I think.

Because that's that's kind of what happens with a lot of big jets.

Uh so you're not alone in this.

And I don't know, Carlton, if um 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 with Russell about getting some help uh from the documentation side to the Django project.

Well, this is something that's I think is a really good idea.

We've got fellows.

Um, I think we can talk about this.

I think this is uh you know, an i just an idea and it's a good idea, but we've got a couple of fellows whom we work on ticket triage and we work on um in all sorts of things.

I wonder if it would be possible, and it may, you know, I've got to check about the DSF's um uh non-profit status and all the rest because it's there are limits on what you can do.

For instance, Marit Maris and I, we're we're not um we're not contracted to code on Django, we're contracted to um work as community managers almost to manage the manage the issue track and resolve issues like that and do the releases, but coding isn't something which a non-profit is allowed to pay for because software development doesn't fit um according to US tax laws, which is fair enough.

Um so I I just I need to check about the the writing, but one idea was could we get a docs fellow?

You know, does the does the um DSF have capacity to bring someone in, maybe part-time or full-time, to work on the docs?

Because we have uh these kind of information architecture issues that we've talked about, but also we've got over a thousand docs 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 even their first language, so you know

No, like there are some um non there are plenty of um contributors whose second first language isn't English who have better English than I do by uh you know a country mile.

But did I

English is not my first language.

Well, that's because you're it's almost, it's almost I'm from Israel.

Yeah, uh so I grew up with English at home uh 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.

Uh, but there is actually an advantage, just aside uh segue, there is an advantage sometimes at 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 uh classmates because you study it much more structured way.

Yeah, so in a my uh much more formal and uh and structured way.

But I want to I want to comment a little bit about the Dox Fellow idea because I think you ask 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 pro 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.

Uh, and I would, for example, be able to dedicate myself to doing the the information architecture, uh, tackling, and you know, figuring out how to triage, you know, dock tickets and stuff, it's bet 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.

And 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 docs fellow, I think it would be really beneficial.

Uh, 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, uh, future people.

They might be even might even be able to do training, uh, 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 uh on board onto the project would be useful.

And obviously what happened after DjangoCon 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 I I think 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 is documentation tickets.

And you know, exactly as you talked about, the front page isn't great, and I just it's just a matter of it.

No, I mean look, don't get me wrong.

Loads of effort's gone in, it's all good stuff, but the reality is we find that we find that there is barriers to participation.

We have people who like, I just couldn't get started contributing.

It's like, but it's not that hard.

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 uh projects don't realize is a factor.

And this is part of the um justification, I say, or something like that, to bring in a fresh perspective.

Because if you're getting someone an like a someone who's an expert in their field giving an opinion or analyzing where you are at, they don't have um all the history in their heads, right?

And I mean, a lot of projects that I do consulting for, um, they say, Oh, you know, we started out, we just had a README, 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.

Um, 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 gonna 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 DjangoCon, 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 you 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 it could theoretically imply that the ticket management itself could use a fresh look because, for example, uh, I don't remember if you break down um uh coding tickets in uh according

to like epics or stories or something like that.

Like if you have a a big feature, do you create subtickets or subtasks, you know, for the different components?

Um, this is this might be something that documentation tickets can benefit from.

Yes.

Because you can say, oh, document the RM, right?

That that's that's a huge thing to put in one ticket, you know.

It could just be, you know, document this thing and it doesn't actually have a kind of uh 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.

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 case 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.

Because I'll tell you why I'm asking.

Because one of the advantages of, for example, m 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 um having to like use multiple things in order to achieve a goal, and it requires a different uh 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, um, which helps me, but I also communicate and actually have conversations with the engineers if I need to.

Uh I work from specs, I work from a lot of different types of information.

And if you're looking at um uh a dock ticket that's uh 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.

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 the first time or or for who you're writing for, right?

When like with Red Hat, you 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 that perhaps when you uh don't day-to-day code, you maintain that more.

Because certainly I have that challenge with Django, right?

Is my own comfort changes.

Yes, it's your comfort change.

They're learning.

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, um, 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 uh the virtual compute and 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 and uh that comes in, um, 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, um, but not but not get so far in the weeds um that I lose track of that.

Um, 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, uh 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, uh I wanna let the person know that I'm with them.

Like you probably make this mistake here and there, but it ultimately is a bit of a this, this, this, this, this.

Um, and so maybe the writer in me kind of gets frustrated with that format.

Uh does that is that something you think about, or is it fine to just have like a recipe list for a particular feature?

That's a joke.

Oh, is that really?

But it depends.

When I first started learning tech writing, um, I got a great piece of advice where you have to keep the language level um at fourth grade level American English, right?

So present simple, keep your sentence structure, super simple.

So this is an advice that I got for working on enterprise documentation.

Yeah.

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 um, 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 uh personal, you know, it it does 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, 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, enterprisey or you know, um software projects that are aimed at um, 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, you know, 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 in 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 set 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 it is 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 uh to achieve that goal.

So Right.

Well, and it part and part of it too is the I I mean, I joke with some of my friends, happy path programming, where you just say, you if you like go 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 um 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 you're gonna make them because I made them writ

ing this tutorial and presumably I know something.

And I think as for for independent uh folks or people who are involved with open source projects, when you write tutorials, uh, especially for beginners, uh, there's definitely space for um positive reinforcements and validation.

Um, and for example, what we do, uh sometimes we'll say, instead of saying um 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 it's gonna fail.

You know, so we try to kind of help them get the foundation uh 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, you know, there are different ways to kind of um try to channel uh the user to towards the right path.

Um on the other hand, I have to say that, you know, and I I think I talk about this in my talk because uh 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 known what they actually said.

I try to stifle the urge to say I told you so, but I'm definitely thinking it when stuff like that happens.

Well, general.

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 say

Yeah, well, it comes in phases.

Yeah, the defiance c go comes in waves.

So I know a few adults who are like that as well.

It's not just the kids.

Yeah, yeah.

Uh one thing, my last question, then Carlton, I feel like I've dominated the discussion, is I wanted to ask you about so opinions versus best practices.

And maybe this is, you know, so if someone's if there is a Django uh 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 and I had a podcast on how does 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 uh 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.

Um that's something that I I think a lot about.

I it would be interesting, I don't know if you could do that in the docs, right, Carlton, to say, like, for example, like the docs 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 start project or not?

Well, and I yeah, and even custom user model, it's like, well, you could have the user profile, right?

It's not like where is the space for the discussion, which is really what this podcast is about, is having the discussion rather than just a list of things.

So, for example, if you have uh 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 uh uh or do you customize the component, right?

Um, 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

So, how do you help people choose their own adventure, right?

Um, although in choose your own adventure books, the ending is usually there's only like uh maybe one or a few uh different endings you can have.

Um this is a this is a big question.

I mean it's a big question, and I think that uh so some solutions I've seen, for example, um I 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 undercloud, the overcloud, and then the 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 uh a pre-deployed uh undercloud, 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 uh good to have everything documented from start to finish and then say you can skip this.

Um, but it's usually better, and I'm gonna give this advice in general when you whenever a user opens a documentation topic whether it's in a web browser uh well I'm thinking it's a web browser um because that's how usually things go it's usually better to have things self-contained uh 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 l

ink to a different but 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 gonna need to figure out how to um 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 case is right

see as a best practice so that's something that you need to keep in mind it's kind

of scary right

And so you want to make sure that if they do that they get to where they want to go.

He would answer every single question 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 might mention these things but this isn't the time or space to get into it which is I think the point you were making.

Right crucial 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 to

pic but you need to explain it very clearly that this is not necessary right this is an optional or an 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 the concept information for example can be why would I use why would I go to this part this fork or this fork right um 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 uh side links and make sure that it doesn't distract them from what they're actually trying to do.

thing and they they'd ask for a solution.

So they they they define the problem right they're the client they they tell you what you want 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.

you're consulting to the most common use cases so let's say you have a hundred 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 um trying to get people not to get distracted into the week

ation details a lot of times um you might find that uh easing their mind about the details uh might help them accept or adopt the overall solution that you're proposing.

I mean when I interview engineers about documentation you know I'm always you know asking them uh questions to possibly that and 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 uh and get feedback right so it's the basic con

cept 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 at a conference and it is expected and encouraged that people will not necessarily challenge but try to understand uh and everybody learns in different ways so people might ask you different questions

and you know we'd got this getting started guide but going through it with 40 people we found you know all the issues it was amazing because they having in this massive group there going through it they were sort of 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

al and then they ran the workshop with the first set of 45 participants and at the end of the workshop uh 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 sprints 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 contribu

tions ever.

If you create a new set of docs, especially tutorials, if you get people to test them and then help you fix them and make them better um it also means you don't have to do it alone.

You know that's something I'd really like

So that could be a nice exercise for that.

They put workshops and they're putting so many people through it.

And yet there seems to I 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.

Well, in the beginning, I remember we had some trouble because a lot of people were lost afterwards and they were like, well, 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 uh junior level engineers or programmers from the alumni, you know.

So the the secret was to collaborate with uh with open source companies, outsourcing companies, whatever companies, consulting, um, to be able to continue the training.

Um, so and that's again, it's a human factor and it's collaboration.

Um, but I think getting people to practice is probably the most helpful thing.

You know, there's no substitute for uh we we say stage time in theater or you can say flight hours, you know.

Well, I think it's guided practice, right, is what really is you what people need when they're starting out.

And I mean I

think structured practice, maybe not just only be there with them, but give them uh feedback inter iteration.

I mean, like so this this site, which would be learnjango.com, I mean uh 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 you know, like Django admin, there's so many things you could do, but um like I've I'm gonna have a 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.

I get excited.

I mean, Carleton barely gets a word in this podcast, so I I can empathize.

And one of the things we try to do, for example, at Red Hat is really give a lot of code examples, give a lot of um 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 um 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 Git, you learn how to, you know, structure your folders, you learn how to set up your uh 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, I would really get lost before I even knew what to do first.

Carlton, is there anything you want to know?

You know, I again just constant just thinking about all that's been said in you know, I always get really blown away whenever I talk to Mikey.

It's just like, yeah.

Because it's such an it's such a you know this is do you remember the literate programming thing?

This uh Donald Knuth had this um idea that you could write this beautiful book and code and programming in this and and uh execute buildable code in the same thing um in the same artifact.

So for me, exactly but in the Django community.

Yeah, exactly.

And in the Django community, we've 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, wordsmiths 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 in?

And a similar way that you have the Django Fellow, they take care of you know, triaging, release management, all of that sort of uh 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 you 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 architect, you know, that's just naming things is hard.

But uh the function of that person will be to give uh 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, yeah, right?

So the all the 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?

Yeah, what's more important?

How far should I document this?

Should I just do it in 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, however, you make the decisions about what to code can also apply to making decisions on what to write.

No, it makes sense.

It's it, yeah, as I say, blown away.

Great.

So your personal site is Dockside of the Moon.

Is there anything else you want to call out if folks want to get in touch with you?

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.

Um, so yeah, docksideofthemoon.com, or you can follow me on Twitter.

Uh, I am that docs lady on Twitter, GitHub, and IRC Freenode.

Um, and uh please follow Write the Docs.

We have conferences in Portland, Oregon, in Prague in the Czech Republic where I live, uh in Australia.

We're also looking to do an East Coast conference next year.

Uh all of our conferences are small enough to have a lot of Pac-Mans.

Um, 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 a community manager, if you're a designer, if you're a librarian, support engineer, we love all everyone.

And we do believe in collaboration.

Uh 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.

Well, thank you, Mikey.

That was uh just amazing to have you on.

Have a great one, guys.

Take care.