Transcript: Technical Writing - Mikey Ariel

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.

Hello, Will.

And this week, we are very pleased to be joined by Mikey Ariel to talk about technical writing.

Hi, Mikey.

Hi, Carlton, Will.

Hello, Mikey.

So we were just discussing off-air, you wear a number of hats.

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

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.

have online spaces for anyone who cares about documentation content communication and so on

mainly in the software industry and 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 there yes of course

so the co-founder of write the docs is also the co-founder of read the docs so eric holscher

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 um with a different team so he basically has two projects or ventures the other

thing that eric came up with was the the famous pac-man rule right at conferences absolutely and

i love the pac-man rule 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 so do we do they want me to run down well we do that yeah you can tell us all about but we do

that jango 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 ah okay uh that's great to hear

that you're doing it in jango 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 yeah

it really works well so that's cool so um i want to ask about your background mikey but before that

what are the standard paths to get into a technical writing role? Or are there 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.

How does one get into technical writing? 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 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 realize 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.

Um, but, uh, generally up until recent years, if you want it 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 tech journalists uh people who um studied english people who were doing i mean we've

i've met people who 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 right i

was uh 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 a 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 uh 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 um skill yeah uh because that's the part that really makes the difference between

let's say technical writer and the developer right because we deal with words right uh that's

the main thing well but you also said something really um quite controversial was that uh we have

to document our code like you you kind of implied that that was true it's so yeah carlton's is so

clean it documents itself no no no i'm joking document yeah self-documented code is code you

wrote recently that's my that's one of my favorite controversial things to say good code you wrote

today even yeah 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 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 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.

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 a decent introduction, right?

You need a decent Git readme or you need a tutorial or getting started or something.

You need to find a way to capture the attention of today's modern, impatient and smart users.

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 that's where technical writing, even though 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.

Right. Well, marketing is another thing that I think developers are famously bad at.

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 I always try to diffuse a bit of anxiety or resistance when I talk to some developers because they say, oh, I'm terrible at documenting. I'll never do it.

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

Exactly. I mean, 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 IDEs 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 don't have 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 choose to focus on tech writing because I like it more.

Well, how would...

Go on, Will, carry on.

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?

And I'll tee that up in the context of, you know, so with Django, Django has fantastic documentation.

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 it 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 uh yes and that's actually something that has been um 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 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

um 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 well i have to i have to come to

our defense there we do have topics and tutorials and reference in different sections and you know

there's how to's and there you know there are there have been historically 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 yes i've tried many times uh i think every time i run a doc sprint

at a django event i refresh my uh my knowledge of the django docs um structure and every time

i'm like oh right i remember this you know because i always i always say you know if i'm new and i

want to get started i get lost within about five minutes there's just so much of it yeah i know i

know but this is i mean that's the thing and 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

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

right well and i think yeah i like i like that section of your talk uh from django con this

year which we'll link to where you you had that picture of the plane and 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 infrastructure 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 right well i think what's 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 going to 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 experience for someone but the challenge 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 in if you miss us miss a thing you're just gone and so it's all about the assumptions

so anyways i so yeah maybe that ties into the use base 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 almost...

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. Right? I mean, it's you're absolutely

right. And I see this in, in smaller projects, but most but the problem is bigger in the like

you said, the heavyweight sort of doc 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 doc set, but that's a different thing. I think that what you're

describing is quite um uh a common uh challenge uh and one of the things that i 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, 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. 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 um at

red hat and a lot of other things where you have almost like a wizard you know or you do 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 a tad set of topics which is really cool in theory but a little bit hard to

implement well i'm i mean yeah i'm doing i'm sorry to interrupt carl yeah i mean i'm doing

exactly that. I mean, so by the time this airs, I'm having a site, learn Django.com. It's just

dedicated to Django. And I think it's going to 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, 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.

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

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

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.

Oh, that's great. Yeah, I think in general, this 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? 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 and 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 going to end up with a lot of specific reference documentation, but you're going to 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 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 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.

What's more work, I think, is the issue. I mean, that's what I see more and more.

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 is reading it?

You don't need to do that.

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

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

If you are an advanced beginner, well, here's five different ones.

You know, that's not too hard to maintain, surely.

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 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 path for that as well and they should focus on different content yeah it does it

does i'm sitting here thinking i'm just sort of listening to you the two of you talk and thinking

about how all this relates to the Django project because 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 home page and the home page 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 and then I'm

thinking about the you know 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 it's just a massive challenge i think it's

yes it's a big project and the bigger the project gets uh the harder it is to chunk information in

a way um that it won't get over compartmentalized right because that's that's kind of what happens

with a lot of big checks 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 yes with russell about getting some help uh from the documentation

side to the django project yes no i mean this is something i don't know if we should talk about

well this is something that i think is a really good idea we've got fellows um i think we can

talk about this i think this is you know 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 you know 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 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 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 docs fellow you know does the does the DSF have

capacity to bring someone in maybe part-time or full-time to work on the docs because we have

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 but sometimes they're

better writers i've found oh yeah 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 a you know a

country mile but did i tell you a secret english is not my first language well that's because you're

It's almost. It's almost. I'm from Israel. 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 a side 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 classmates, because you study it much more structured way.

Yeah. So much more formal and and structured way. But I want to I want to comment a little bit about the Docs 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 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 might be enough to just get someone for a few months 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 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 be able to do training, you know, webinars or presentations or write tutorials on how to get the basics, you know, for your contributors.

Anything you can do to help people on board onto the project would be useful.

Yeah, no, I think it's a good idea.

And obviously what happened after Django on 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 think, you know, there's obviously the ORM and the admin, which are big issues in Django.

But then 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 see it as just a massive...

Well, I think it's okay.

Yeah, it's okay.

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

Well, the thing is about the document...

Loads of effort's gone in.

It's all good stuff.

But the reality is we find that there is barriers to participation.

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

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

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 like 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 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 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 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 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 according to

like epics or stories or something like that like if you have a a big feature do you create sub

tickets 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 orm right

that's that's a huge yeah it's not possible is it put in one ticket you know so it could be that

people are looking at those tickets and a they might be not written um in a helpful way 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 i think most of it is that it's at this stage because django is very mature and

because the features are mature and, for instance, 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 use case

which 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've got to have the ability to phrase it in the clearest English.

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 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 um 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 a doc 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. 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 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?

It's my own comfort changes.

Yes, it's your comfort zone, right?

I have to work harder to...

So you remember 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 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 keep that fresh perspective.

And specifically in OpenStack, but actually in a lot of our products, there are 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 and high availability.

Somebody else in our writing team is in charge of networking.

Somebody else is in charge of storage.

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, um, but not, but not get so far in the weeds, um,

that I lose track of that. And how do you, so this is a question I have, 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, 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 you 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 with 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?

I'm going to use the classic answer of it depends.

Welcome to Django Chat.

Oh, is that really?

Yeah, every episode.

We always try to be opinionated, but, you know, some things it does depend.

But it 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, key percentage structure, super simple.

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

No, I believe the advice, yeah.

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 people who need to have that personal tone okay

So if you're talking about the tone of the documentation, for the most part in the bigger, you know, enterprise-y 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, 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 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 to achieve that goal.

Right. I like that. Well, and 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 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, don't become discouraged if you make them because you're going to make them because I made them writing this tutorial and presumably I know something.

Right. And I think 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 the troubleshoot, we can say, make sure you put in this variable in this format, otherwise it's going to fail.

You know, so we try 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 towards the right path.

On the other hand, I have to say that, you know, and I think I talk 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.

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 happens well you know i mean children will be

children right 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 i don't know

what your kids are like but mine are very much like because you told me i'm doing it the other

way oh of course yeah well it comes in phases yeah the defiance comes in waves so exactly i

adults who are like that as well it's not just the kids yeah yeah well um 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 so opinions versus best practices and maybe this is you know so if

someone 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 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 project structure, there's, you know, a couple of 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 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 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 that makes sense and

it's a good question to ask because that's kind of throwing back to the uh 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

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 oh no it's a choose your own adventure yeah yes exactly

exactly 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 maybe one or a few uh different endings

you can have um this is a it's a big question i mean it's a big question and i think that uh

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 undercloud, the overcloud, and then the guest instances, which is how 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 then say, you can skip this.

But it's usually better, and I'm going to give this advice in general, 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 different set. 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 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, it might be better to break it down to multiple procedures, depending on how common the use case is, right?

Or give an opinionated route and then put in sort of a sidebar.

say and you could do this at this point but come back to that exactly exactly so that's what that's

what i do as an aside yeah as the person who's creating the documentation you are already

considered the expert uh from the reader's 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 it's kind of scary

and saying, well, it is 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.

Yeah, I think I like that, as we said, the addressing 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 best teachers I ever had would was actually for accounting in business school.

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.

Exactly, exactly.

So, you know, telling users which information they need to focus on at this point is 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 topic.

But you need to explain it very clearly that this is not necessary.

Right. It's 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?

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.

Yeah, well, I think, I mean, Carlton, when you were a 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 Y 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 synopsis.

i mean there's one thing i found with like people you know clients who'd be hiring you you'd have

the expertise you'd be there to build the thing and they'd ask for a solution so they they define

the problem right they're the client they tell you what you've got 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

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

um 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 you know and you in fact you're doing them a disservice by

over complicating the story yes well let's just say that it's very rarely a tools problem right

and that's the psychological part that um 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 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 um you know this component or that

solution you know if they want to get into the implementation 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 yeah see a lot a lot of times they just want in that particular

circumstance they just want you to um justify your choice so that they know to trust you that's

yeah totally which is fine yeah yeah absolutely that's a conversation that needs to happen

And as long as they're not being malicious or especially trolly 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 them 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 at 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 so we

did um talking of workshops i did uh getting contributed to django sprint at django con us

this year and you know we've got this getting started guide but going through it with 40 people

we found you know all the issues it was amazing because they big having in this massive group

there 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 great i mean when when i

you're taking me back now to my first uh django girls workshop the first one that was at europe

python uh 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 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 contributions ever so i don't know if you will have a chance to do that

but maybe that's uh that's also a an exercise that can really help 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

of 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 for them and there's

something so good about the django girls process they put workshops and they're putting so many

people through it and yet there seems to 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 yes 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 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 say stage time in theater or you can say

flight hours you know right well i think it's guided practice right is what really is you what

people need when they're starting out and i mean structured practice maybe not right which is hard

be there with them, but give them feedback into iteration. Right. Or even just do this next. 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

you know, like Django admin, there's so many things you could do. But like, I'm going to 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. Sorry, I keep cutting you off. I get excited.

I'm the same way. I mean, Carlton barely gets a word in this podcast. So I can empathize.

Yeah, I totally get it. And it's something that's really useful. 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 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 Git, 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, I would really get lost before I even knew what to do first.

Totally agree.

Carlton, is there anything you want to add as we head out?

You know, 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 a neat, it's such a, you know, this is, do you remember the literate programming thing? Donald Knuth had this idea that you could write this beautiful book and code and programming and execute buildable code in the same thing, in the same artifact.

Yeah, it's a lovely dream.

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. But in the Django community is actually collaboration.

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 lay the breadcrumbs out to entice those people to come and join in?

Exactly. And a similar way that you have the Django fellow, they take care of, you know, triaging, release management, all of that sort of project architecture thing, which actually enables 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 architect, you know, that's just naming things is hard.

But the function of that person will be 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 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 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 however you make the decisions

about what to code can also apply to making decisions on what to write.

Yeah. No, it makes sense. It's, yeah, as I say, blown away.

Well, once I get that merch 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 Dockside of the Moon.

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

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, DocSideOfTheMoon.com, or you can follow me on Twitter.

I am ThatDocsLady on Twitter, GitHub, and IRC Freenode.

And please follow Write the Docs.

We have conferences in Portland, Oregon, in Prague, in the Czech Republic where I live, 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 super well thank you mikey that was just amazing to have you on

okay wonderful have a great one guys take care