Docs or it didn't happen! (with Q&A)

Speaker 1: Hello everyone. It's really great to be here. This is my second Django Con Europe ever. The first one was in 2016 in Budapest. And I was not able to enjoy it as much as I am enjoying this one. So it's really great to be back. Uh today we are going to talk about Doc Story Didn't Happen, which is how I kind of live my life. I hope to see more Docs talks uh next year, but um let's see. Right, so why are we here? Here as in in this room, not on this planet. This is not an existential question. Uh why are you sitting here in this talk? Because we want to have more users, more contributors. We want to increase adoption of our open source projects. And we are hoping

Speaker 1: to believe that documentation can help us. But something, something is stopping us from writing documentation. Um so this is a very special edition, uh as Sarah said, uh of this talk, and this is only something that I would do for a Django community, which is I'm gonna take questions Because I never take questions. And I did get some questions uh in advance on Twitter, uh, so I've already incorporated these into the end of the presentation. And I'm also going to encourage you to write your questions on Slack. There's a chat a questions channel on the Slack. We have a great moderator for online questions. And then if we have time at the end, maybe I'll let some people come up to the microphone, but we will see. The reason I don't normally take questions is because most of the questions are best answered when you ask me face to

Speaker 1: face And when we have a laptop with us, right? So a lot of the stuff is, I have this README, it's in really bad shape. How can I fix it? I can't really answer this from this stage, right? Um so I do want to encourage you to come and talk to me afterwards, write to me on Slack, Twitter, email, I'm here for you. So Who am I? As uh they said, I am that docs lady. I have been for the past five years or so. I mean, I've been a technical writer for about ten years. But five years ago I joined Red Hat. I live in Prague. I work at Red Hat. I document OpenStack platform, which means I read a lot of Python. And I used to work in containers and I kind of played with them like this. Like most of us. Before that I was working in the Java space. I'm also a recovering Scrum Master, and I still love Agile and DevOps.

Speaker 1: Um, I really do. I'm on the core team community management of Write the Docs, together with my friend Sasha Ramain and two other people. And if Write the Docs Sounds like Read the Docs to You, then it's because it was started by the same people. So Eric Holscher is the co-founder of both Write the Docs and Read the Docs And it's a wonderful community built on open source principles, specifically built on Django and Python community values, which is part of the reason I really love it. I'm a Django Girls alumni. I used to organize workshops in Czech Republic and I roam around PyCons and Django Cons in around Europe. uh coaching developers on documentation, running doc sprints. I was uh very fortunate to join Django under

Speaker 1: the hood for a few years. to run sprints. I'm also contributing to Fedora and I'm the co-author together with Sasha of the Happiness Packets Project, which has nothing to do with technical or software, but it has everything to do with being nice to people. So I highly recommend you to look it up. I have stickers for most of these things out in the front and also in my bag. So what am I going to talk about today? The main parts of the presentation are going to be content strategy, which basically means think before you dock, which I hope you are also implementing in your coding. So it's the same thing. Plan a little bit, save a lot of time and aggravation later. DevOps for docs , because when I first started working as a technical writer, we used FrameMaker, which is a very Microsoft wordsy type of to

Speaker 1: I see some heads nodding. Yes, I'm so happy, and that we don't use that anymore. And then Elk XML came along and everybody was happy and now XML is going away and everybody's even happier So I've seen the the technical spectrum of of the technical writing world change quite drastically in the last 10 years. So there's a lot of cool stuff happening there. And the last thing is the community spirit because we do not work in a vacuum and we are all in this together. So I would like to invite you to join the Documentarian Club, currently populated by Capibaras and humans. And what is a documentarian? A documentary, this is from the Right the Docs um manifesto. A documentarian is someone who cares about documentation and communication in the software industry, regardless of job title.

Speaker 1: Okay, so it's no longer tech writers, developers, you know, designers. Everybody can care about communicating and describing the software regardless of job role. So we are all documentarians. Okay, it doesn't matter if you're a community manager, if you're a support engineer, everybody can have something to do to make this a better place. It's the same as we're all involved in the software development cycle in one way or another. So, content strategy means asking the right questions ahead of time. And I'm going to Give you a slight bit of different way of thinking about this, okay? Because this is the kind of strategic thinking about documentation that I have to deal with a lot when I work with engineers at work, for example

Speaker 1: Because uh I often find that for some people when you create a tool, when you make software and you send it out to the world then you want to tell everybody everything about it. You know, so it's almost like this existential validation. You know, when you're a child and you show your drawing to your parents, if they don't acknowledge it, it means it doesn't exist. Right. So we are trying to change that way of thinking, whereas you no longer think of this as what is in it for me as what is in it for my readers, and my readers are my users. Okay, so I want to create value in the documentation. I don't have to document every single thing anymore, which is quite nice actually. So I'm gonna use the five W questions. The why, what

Speaker 1: uh who, what, when, and where. Probably in this order. I can't remember. Um So why do I need to know this? Is the first thing that you should consider. Why do I care about the documentation that I'm reading? Which is exactly the same question as why do I care about the software that you're trying to get me to use? Right? So if we're thinking about this not from a hey this tool can do all this cool stuff is ask not what your tool what your tool can do for you is what you can do with this tool. Okay So um so as an example I'm giving the uh this example which is a quite a uh uh Interesting thing when you think about it because we have this problem in many of the bigger documentation sets, but also uh in the smaller projects is something you can consider.

Speaker 1: Um something we've been working on at Red Hat for the last few years is Right now, our documentation tells us what every single button does. But what our readers want to know is how to fly a plane. Okay, so it's not gonna matter if they know what every single control I mean it's this is kind of a janky airplane. I don't know. It looked nice in my laptop, so I might have to change this screenshot to something a little bit more modern, right? But I've run into software that looks like this, okay? So you get all sorts. But this is exactly the strategic thinking that I want. Why should I care? what every single button does when I just want to know how to fly a plane. So goal-oriented documentation is the key. And then the next thing I want to know is who my readers are, which is the same question as who is using my software.

Speaker 1: So as an example, I'm going to give the GNOME help, which I love, and they've been doing this really well for years. This is where you get to the static duct site. So if you type in help. gnome. org and then you get to their website, they don't know who you are when you get to their website. So the first question they ask you is, who are you? Okay? If it worked for the caterpillar, it can work for these keys. So depending on what you choose, you get entirely different sets of documentation. Okay, so persona-based documentation is something that we're really trying to emphasize here. So you get the information that you need and you don't get the information that you don't need. So if I'm a developer, I don't really need to know how to use different things on the desktop. For example. And by the way, the users

Speaker 1: option is the same screen that you get if you click F1 in your GNOME desktop So in the right context, it's okay to display directly the user's help. Because I know if I'm clicking F1 in my desktop, I probably have a question about something that I'm using right now. But if I'm an administrator or a developer, I don't really care And then the next question is what? And what in the sense I mean what type of information? Okay. So depending on Who your readers are, okay, and why they are already opening the documentation, what a goal are they trying to achieve? It affects the type of information that you're gonna give them. So for example, if you want to showcase different aspects of your tool or of your software, you can give them fancy diagrams or architecture charts.

Speaker 1: Or if they're already coming into your README, for example, on GitHub, then you can assume that they are certain personas, and then you can give them different types of information. And for the example for that, I will go to our humble README. Some of you already know, I've heard a great talk. Hello, my name is README. By Raphael, he's very good. Um so one of the things I really like, this is a project that I used to be involved with at Red Hat called MiniShift. And it's a localized containerized deployment of single node OpenShift. And we had a small team, and I was really lucky to be able to get this project docs on the ground floor and actually structure it properly instead of coming in like a documentation Mary Poppins and just trying to clean up your help you clean up your house.

Speaker 1: Um so I use this as examples and I will use it un until they do something to it and I hope they don't. The reason I'm showing you this README is because it's short. Okay. It's short and it acts like a portal to your open source project. So if I have A GitHub readme, that's the homepage of my code repository. It's also the homepage of where I'm most likely to get people who want to contribute. Or people who are slightly more advanced than the average user who the so if you have a static doc site, help. whatever. org, you know, then that's where you get most of the common personas. But your GitHub README is a little bit more specialized than that.

Speaker 1: And I get a lot of questions about README's. And I say, think about the README like the foyer or the entrance to your house. You do not want to have all of your crap there, okay? Because people can get really disoriented. And a lot of times projects start small and then they have Just a few bits and pieces of information in the README and then as it gets bigger the README gets longer and becomes a dumping ground for everything about the project. At some point you're gonna have to see how many times do I scroll To get to the end of the README. Okay, that's a good indication because if you do it more than a few times, then you probably should split up your information So this README has everything. It has a table of contents. It is written in ASCII Doc, but uh GitHub will render most Markup languages for you on the fly.

Speaker 1: It has a welcome. It has which um Projects we have used uh to fork this is the fork of Minikube, Minishift Minikube, uh from Kubernetes. Uh how to get started We already have documentation, some smaller help topics on installation and configuration. So it has links there. It has links to the documentation. And a very important part, it has the community section Okay, because a lot of times people will get to your GitHub README wanting to contribute. And this is what's going to help them get started. Okay? So a lot of times I get questions, how do I get people from users to contributors? Welcome them. Show them how it's done. Okay? Show them how they can get in touch. Mailing lists.

Speaker 1: You know, if you have contribution guidelines for patches, code patches, and documentation patches. So the next thing I want to ask is when? When do I need to know this information? Let's talk about error messages a little bit. bit. Okay? And troubleshooting information. No, error messages is next. Sorry. I just re-chained re-edited a little bit. So the when means at which point of the usage cycle of the software, am I going to need encounter documentation? So yeah, error messages, okay? I will talk about them a little bit, but I'll show an example later. So when I see an error message, something's broken, okay? And I am not in a happy mood when things get broken. So I need to know how much information to deliver to my readers when they see an error message.

Speaker 1: A hint, it's usually a little bit more than you think. Okay. Most of the time when I edit error messages, I need to expand them rather than compress them. So from my experience as a writer working with uh with developers So uh and it also helps you figure out how to optimize the content delivery. So for for the when, I want to show the Arch Linux wiki, Arch users. I can't see anything. Yeah, that's about the same. And that's about similar w and when I ask it in the conferences, but I love this wiki because they they love this wiki, right? And why do they love this wiki? Because of this Because it's optimized for impatient, frustrated, I've already tried everything users. Okay?

Speaker 1: It doesn't need to look sexual. You know, it needs to work, all the information is in there, and you basically just search for whatever it is that you need to do. So by the time I get to this piece of documentation I have tried everything else, and so I don't want to waste time on browsing help topics. I know roughly the keywords, and so you can optimize your content delivery based on that And the last question I want to ask is where. And where I want to talk about error messages again So the where and when are connected, obviously. Um because by the time I get to an error message, I'm like I said, I'm frustrated. But How much information do I give at each platform of delivery?

Speaker 1: So you can have a static doc site, you can have a README, you can have an error message, you can have embedded help, you can have hover text You can have a lot of different ways of interacting. You can have man pages, even doc strings in your API, which would hopefully get generated into some kind of API reference. There's a lot of automation around that already. But how much information do you give at where? Um so you need to make the information accessible and uh because if you can write if you write the greatest documentation set ever, but I can't find it. It doesn't exist. I'm sorry. You know, so you have to make sure that people find this information. So, as an example, uh one of the things that we worked on on Minishift was um there was a problem

Speaker 1: where if you install too many packages on the root file system of a minishift VM, you can lock up the VM and it'll just get too full. The problem is we couldn't stop the users from doing this. Okay? And unfortunately, from our experience, a lot of times people will try to stretch the boundaries of the software you provide them unless you actually block them. Right, so the proposed uh draft for this error message that you see in the terminal was installing additional packages is not supported. For more information, see the documentation There is a problem, there are several problems with this error message. Okay, one is not supported in tech jargon means physically blocked, cannot technically be done Which is wrong

Speaker 1: because the users can install whatever they want on the root file system. It's just going to cause them problems. So first of all, that's incorrect. Second is why is this not supported What is the problem that this is going to create? And just sending them to a documentation link feels a little bit like a cop-out. You know? It's like you can't do this and then go and copy the link and put it in your browser. You know, so we are not giving them enough information that they can trust us Not to do this thing that they're not supposed to do. Okay? So why is this unsupported and what are the alternatives? Are the questions that we should ask. And the answers are going to affect the error message that we eventually came up with.

Speaker 1: was installing additional packages on the root file system might exceed the allocated overlay size. We can assume that they know what overlay size means Okay, so these are assumptions about our users that we are making. I did not know what overlay size means, but as soon as I figured it out, I was able to say, okay, so that works. And it will lock the mini shift VM. So we have action. Result, cause, okay, action cause result, locking the minishift VM, proceed with the installation at your own risk, which is something that Linux users really like to hear. Um it's quite common, right? So I mean you don't have to be like very fluffy in your in your language. So this is a relatively casual uh error message and then we give them the link in case they still don't believe us.

Speaker 1: Okay. So if they really don't believe us We have a help topic in the troubleshooting guide that actually describes in many more words basically the same thing that we said in the error message. Okay. But as far as that, so it gives you the mount and the SDA and then like if people really want to geek out about why is this technically a problem. Okay? But for most people this will be enough. Okay? And we do give them a link to the next thing, to more information. So where do I deliver the the information? How much do I give? you know, why do I need to know this? Who needs to know this? What do I need to know? When do I need to know it? And where am I going to get this information?

Speaker 1: This is basically content strategy, which kind of, you know, it could sound like a big, you know, anything with the word strategy in it sounds kind of big. But if you ask these questions, it could be a matter of a five-minute discussion that can help save you hours, you know, of a lot of documenting uh documentation work that you might not even need to use anymore. Okay. So let's talk about DevOps for docs. I can't say DocOps because some company copyrighted it And it's not even a DevOps thing that they did. I don't know. Um so processes, tools, and workflows. Oh my. The name of the game for us

Speaker 1: in the tech writing field over the last five or ten years has definitely been integration. because we all work together. I am surrounded by extremely talented and very skilled engineers who make wonderful DevOps tools for themselves. So why can't I use them? You know, why not? Okay, so there are some things here that if you're active in the Django community, you will already know, but you'll get validation, right? Which is also nice. So things that are being done right, I will call out. And if you find things that you are not still doing, not yet doing, then hopefully this will inspire you to do something a little bit different. So Docs 's code, uh, as an example you have the a documentation

Speaker 1: a docs folder inside your GitHub repo Which makes it easier when you submit code patches to also submit documentation patches if everything is stored in the same place I get asked a lot whether documentation requires its own repository, and I hate to say this, but it depends. It depends on how much codes are you trying to manage? How many code repositories do you have? Because if you have something with 12 code repositories And then they all get integrated into one big platform. If we're looking at Red Hat OpenStack platform, for example, it's got like dozens of upstream components that we pull in into a single platform that we package together and put and channel downstream into

Speaker 1: our customers Okay, there is no way that I can edit every single component in the upstream OpenStack repository and get a meaningful set of docs, especially if we remember the goal-oriented docs. You know, so the all the upstream components, for example, in the OpenStack Foundation repositories are specifically in the components that they are relevant for. But when we deliver a platform, then we need to provide end-to-end use case scenarios, how to deploy real-time computing. How to apply AHA proxy. And all of these different things require a different set of documentation. So we have our own documentation repository for OpenStack platform at Red Hat. But most of the time

Speaker 1: This will be enough for the smaller open source projects. Um and the integration here is really, really important. Uh and you can always move it out. But it's really hard to put it back in. Um so hierarchical source content. Hopefully you have a similar thing in your code Where you have some kind of folder structure and then things are grouped into folders, you can do this. Here we have just topics Because it's a relatively small documentation set, but theoretically when your project gets bigger, instead of having one topic for installation, you can have a folder. Okay, and m we try to make it so that the content topics, the the topic chunks are small enough that you can move them around and you can reuse them. So I believe in scroll-free as much as possible

Speaker 1: And then you will be able to have the source file structure mirroring your published documentation set, hopefully. The other thing, and this is something that Django does right, is having an integration of doc uh doc bugs into your issue tracking. That part is done right. The issue tracking itself might use a bit of work, but that has nothing to do with the documentation. But I mean all issue tracking platforms have their upsides and downsides. So uh having a documentation component means you can flag issues as documentation issues. And then you can also mark them as tasks, as bugs. You know, that's the usual thing that you would do for any kind of coding task.

Speaker 1: So if you integrate this, it also helps people feel like, you know, if you have a writer uh who wants to contribute, it feels like they're doing something a little bit more meaningful if you're giving them you know, the ability to say this is a documentation issue at the same level of respect that another that a code a technical code issue would have. So just bringing them into the family, you know, makes them feel welcome. So continuous publication. I remember when we made Dock CDs. That was a nightmare. Uh we don't have to do this anymore. You don't have to do this anymore with most of your software, right? I mean I don't know who even is anybody still writing code for something that gets published on a DVD and not also online

Speaker 1: Isn't it great? And it's less wasteful. So Continuous publication. There are lots of really easy ways to do this. If you're in Python, you can use Sphinx and read the docs. Um ASCII Doctor and ASCII Doc for Ruby. You have McDocs, you have Gitbook, you have a lot of different parsers. A lot of them are available out of the box. You know, even if you have a small project, you can even you just Check a checkbox and GitHub pages will publish your docset for you. You know, so there's a lot of different uh low effort ways that you can do asynchronous publishing. You can uh Put stuff into your build sequence. You know, every time you know you cut a release, you can also cut the release on a documentation. You can version, you can branch, you can do all kinds of great things.

Speaker 1: You also could have like uh previews of your documentation site. Uh at Write to Docs we use Netlify and we have a lot of different Now you get this again. Okay. Okay. No, that's the other one. Wrong way. Okay. We're still good on time. So um what did I talk about? I talked about this, yes. So testing automation is still hard.

Speaker 1: For documentation, because unlike code, prose is harder to compile neatly into binaries. Um so a lot of the tools out there are more aimed for uncovering problems rather than let's say fixing them for you And it's a lot trickier when you're talking about, you know, linguistic grammar and syntax. So I would be happy to hear if anybody's working on cool things. Uh especially there are solutions for things like that, but not so many open source ones. Okay, so I'm only talking about open source stuff here. Um and uh so for example, uh I literally last week found out that one of my good friends from KDE project Uh they built a tool that aims to do just one jab, which is testing code blocks in markdown files.

Speaker 1: Okay, you can run it locally, you can run it in you can put it in your build sequence, and it basically runs Code blocks from markdown files in a shell. Okay, so which shell it is depends on your system. Um and it just validates that whatever you have in your code blocks. works. Now I know for restructure text and ASCII doc in the more robust markup languages, there are tools for this. There's doc tests, there's you can dynamically embed code blocks in your topics. But a lot of projects still use Markdown, right? So this is a quick and easy way to do this and people can extend it and it's open source and you can look at it later. The next one is of course the Trusty Hemingway app, which will help you if you feed, if you copy and paste some text into it. It can highlight some things that are uh a little bit flowery uh

Speaker 1: and probably not so uh concise. Um unfortunately it only works It works best in smaller chunks of text, so you probably don't want to feed a 500-page manual into it. But this is an example of the things that it can do, right? So if you want to get more robust This is where things get a little bit harder. So this is a test automation framework for documentation for English or translated prose. There are open non-open source solutions for this, which I'm not going to mention, but this is a tool that my colleagues at Red Hat Content Services are working on. It's free, it's open source. And it's called Amender, and you basically feed your style guide into it and feed your grammatical conventions to it. And Of course you will be faced with the question, how much do I invest in test automation

Speaker 1: versus how much value I get out of it? But that's something that you're already dealing with these questions when you're coding. So this is another thing that you can consider. And the last thing I want to talk about before I get to the questions part is the community spirit. So when I joined uh Red Hat when I moved, uh I'm from Israel, now I live in Prague. And when I started traveling around, especially Python and Django, and then write the docs , I realized that there's a lot of things that we can do when we collaborate. And one of the great things about working in open source is that there's a lot of that spirit of collaboration. And I mean I'm I'm I drank the Kool-Aid. I'm all in it. And it's really, really wonderful.

Speaker 1: And I'm happy that I get to come here and talk to a lot of people from different roles. And there's a lot of things that we can do to be more welcoming to contributors. And to more users, whether it's from documentation or code or whatever it is to our project. Okay, so it's not just about the code, it's not just about developers, it's about sorry, the community. Okay? So Doc sorry didn't happen. Repeat after me! Doc sorry didn't happen. Let's try this again. Doc sorry didn't happen. Doc sorry didn't happen. Thank you very much. This is not just a Yes This doesn't work at every conference.

Speaker 1: This is why I like this community. Okay. Documentation as a deliverable, as a requirement. Doc sorry didn't happen is not just a funky tagline. It means give me docs or I'm not accepting your patch. Okay? Janger project does this, Linux kernel, OpenStack, a lot of different projects do this. And I mean yes you should actually enforce this, obviously, uh but having it documented on your contribution guidelines is a good start because you're saying this is an official thing, this is a policy Okay, you make documentation contributions into your code contribution policies. Okay? Step number one. And now that you've made it into your policy, how are you going to help people learn how to contribute?

Speaker 1: So you write contribution guidelines. Okay, and and give them help who will dock the docs, you know? So how to dock the docs. This is something we did for NixOS a few years ago. There's a lot of different uh projects who have this kind of thing, and I will talk about this in a second And so of course you want to give them also templates, right? Code templates, you know, a lot of people copy and paste things. Um and Why not have this for your documentation as well? This is a relatively uh this is on the Write the Docs website, and I'm pretty sure we've gotten the most hits is on this page. Okay, the README template. And so whether you're just doing a small README or whether you're doing a much bigger dock set, then templates are great. There are many out there.

Speaker 1: One of the latest things that I've come across uh is something we're doing at Red Hat, which is called the Modular Docs project. So if you're looking at, I mean this is a very small README, it's very cute, but if you want to do a documentation plan, okay, or if you want to actually build a strategy for something that will scale, okay, it's worth checking out this project. Because it gives you we have a reference guide where you can read all about, you know, what is modular documentation. And when I say modular documentation, I mean small Content chunks that are reusable, movable, and you can assemble them in different ways. Uh the terminology is actually Not the most critical part here. You can call them modules, you can call them topics.

Speaker 1: It doesn't matter. The point is this is a free and open source project that we encourage communities to use. Okay, and you can understand things like, you know, and this is based on the topic-based architecture, which breaks down uh topics into concept, task, reference, which is fairly standard in the tech writing world. But what I like about this is we have templates. Okay, so there are templates here for any kind of uh mo for the most part. uh the most common documentation types that you will need. And if you this is a just a raw output of the procedure template. So this is a module and it tells you, you know, it gives you suggestions for naming conventions and it also gives you things like, you know, start each step with an active verb.

Speaker 1: And all sorts of things like that include one command, so it gives you best practices on how to write a task topic And I know some famed people still struggle with this because it's not a lot of engineers, a lot of people who are not writers, you know, just like people have developed a skill set in writing code, you know, I have developed a skill set in writing docs, you know, and it's not something, you know, a lot of people ask me, you know, how do I write documentation if I'm not gonna change careers now. And you don't have to do this because we put out some best practices, thankfully, and some templates. So these resources are available. And then the last thing I want to talk about before I get into the questions is like I said, we are surrounded by humans. We work with humans whether it's remotely or in person.

Speaker 1: The personal connections and the social aspect of working in open source community is much more felt um when you're talking about documentation. Because it's all about communication, right? So I wanna talk about Write the Docs because it's one of the happiest communities that I have been uh very fortunate to be a part of. We have this year we have five conferences. We've been around for six years. I joined uh five years ago We have conferences in Portland and in Prague. Those are our main conferences. And we have new conferences. Well, Australia is in the third year already. We have Cincinnati last year collaboration with OpenHelp. And we have a new one this year in Vilnius in June. Um and this is the place where you go and learn about

Speaker 1: You know, way more things than I talked about today. Like this presentation is kind of a hopefully to inspire you to think a little bit differently, but also to tease you to want to learn more about this, okay, about the documentation world, about content, about collaboration, okay, about communication. So this is my home and I'm really happy to be there. And the other thing that I do is uh I come to these conferences. I've done this in the past at Django under the hood. uh and I've been running documentation sprints. So, you know, next time you go to any kind of Python, Django, or any kind of open source event, you know, know that writers walk among you. And we are here.

Speaker 1: And we might not be the majority at these events, but we do try to get to a wider range of uh of open source and technical events to be able to collaborate. So I'm not just inviting you to come to my home at Write the Docs. I'm also telling you that we are among you and it's It's probably good if you're nice to us, because we might write some docs for you. I do want to give a shout-out for a season of docs. If you know Summer of Code, then it's like this, but for docs. And they're doing it this year for the first time. The application period is open now and open source projects can apply and then you can get writers for free to do things for you and you can get paid and the writers can get paid and it's like a mentorship and it's

Speaker 1: and they can you can help you can get help for open source projects that you would not have otherwise gotten um in the documentation area Yeah. So Google Google season of docs is a cool thing that they're doing now. Okay. We are good. All right, so I have ten more minutes. I want to start um with a few questions that I got in advance. Okay. I I I've been tweeting like hell in the last couple weeks asking for some questions. And I have crowd I have crowdsourced, anonymized, and non-weaponized questions. I do not accept weaponized questions. We may not have time for the microphone stuff, okay, but the online things could happen. Hopefully they are non-weaponized as well.

Speaker 1: I mean if you ask me a weaponized question, you better be prepared to deal with the answer. This is why I don't take questions. Okay, so the first question is about uh in it has to do with grammar syntax and linguistics. And the question was Do you see benefits in using or avoiding pronouns in docs? And then later we've kind of elaborated or clarified that it's also a matter of of gerunds and infinitives. Property X allows you to do Y versus Property X allows for doing Y. And do you have any recommendations on when which version makes more sense or it's more appropriate? So there's a lot a few examples that we were uh iterating on on Twitter until I understood what the question was, but the answer to all of that is minimalism.

Speaker 1: Okay, which means use fewer words. And one of the things, one of the first things that I was taught when I became a technical writer is you have to keep it really, really simple. Okay, and even more simple than you think. And and not as in uh the topics that we write about are so complicated sometimes that the language has to be extremely simple So these are things that uh for example so if we're looking at the examples that uh the question was listing so property x allows you to do y, property x allows for doing y uh with x one can do y with x Doing Y is possible. With X, it's possible to do Y. You do Y with X.

Speaker 1: Okay? Or you do X with Y. Sorry. Because the X comes first. So why am I flipping all of this into you do X with Y. This is a minimalistic approach. Okay? And even if before it was called minimalism and you can Google minimalism, right? So You, second voice. I have notes. Second voice, you in the relevant context. Okay, so you are addressing the user or the reader directly Okay? This is what we try to do as persona-based documentation. So you're not saying you know administrators can do that. We want to make sure that we are addressing the user directly as much as possible Okay. And then the second uh reasoning for this is that things cannot allow humans to do things.

Speaker 1: It's the same way it's an anthropomorphism. I think I'm pronouncing it right. Uh it's a really long word. Uh but it's basically giving human attributes to inanimate objects. And I see this happen a lot. Uh the other um so things like a software or a tool cannot allow you to do something. You use the tool to do something. Okay, so we flipped the way we think about it and it's action-based, goal-based, user-based. The other um side tangent, I have very few side tangents in this presentation. I'm quite proud of myself. Uh things cannot have things, okay? This tool cannot have uh attributes. It includes, it can describe, it does things.

Speaker 1: Software cannot own possessions. Also have is a really dangerous word. Anyway, active voice indicates the goal first and the method second. So if we're looking at goal-oriented wording, and then gerons, which is anything that ends with ing doing streaming, uh browsing, writing, um are grammatically ambiguous and hard to translate sometimes. Um so if you have uh Um probably sometimes if it's in the middle of the sentence it could have different ways to slice the sentence. But generally using gerons is best avoided in regular sentences. So unless you have a title, for example, that says installing this tool, okay? A gerund is fine because it indicates a continuous action and it's not ambiguous.

Speaker 1: Okay, so you have to use gerons very carefully. So that was the linguistic question that I got. The second uh theme, I got a few questions that are actually related. Um and I'm going to have there's a lot of text. here. So I got a project. I know I need docs. I can write, but I know it's not my strength. What do I need to do to make it easier for someone who does have those skills to contribute? When starting a project from scratch, how does one figure out how to structure the documentation and what are the first N things one should take care of? It's very hard for someone to write documentation for a project if they don't know how the project works. How do you best facilitate that knowledge transfer other than of course writing docs? How do you bootstrap the process? I don't know what I don't know, so how can I possibly know what you don't know?

Speaker 1: That's a really good question. And I I have to say, not everybody has enough awareness to even ask this question. Okay, so I thank you for all these questions. And they are all related because the answer is you have to talk to people. Sorry, you know? I talk to people all day. This is my job. I understand that it's not everyone's job to talk to people all day, but this is something that would be the easiest it the easiest way to solve things would be to talk to people. So if I take the first question, you know, how do I get people who might have documentation skills to contribute to the project? So here's a few tips, okay?

Speaker 1: Find people with writing experience as in you know I said we walk amongst you or you can do some calls to action. You find people with writing experience and or who are uh interested in it. Ask them to test your software. Okay, and then figure out what kind of workflow they're using, ask them to give you feedback, and then help you build contribution guidelines Okay. Another thing that I think is great, KDE project does this, and I don't know how many other projects are doing it. I just recently learned about it, is that if you have uh easy pickings or junior jobs flag in your issue tracker, they attach a mentorship to this. So it's not enough to say that something is easy, right?

Speaker 1: Because easy is a subjective thing. Please remember this. Uh what's easy for you might not be for someone else, especially if they're new. So attaching a mentorship to the easy pickings uh issues can help bring uh people in to your project. So it can help um yeah it can bring in new contributors who can fix your docs but might not necessarily have programming experience. Hello? Or even have experience with your project, you know? My my favorite, well, my least favorite uh admission is self-documented code is code that you wrote recently. So I mean even if our so at Red Hat most of our users are developers, but they didn't write the stuff that they're using. You know, this is another perspective that you can put in. And the other thing is you can do is you can facilitate

Speaker 1: skill sharing sprints. So for example, if you invite writers to your developer sprint and then you do some kind of pair hacking or, you know, some kind of collaborations. uh where let's say if I'm a writer I can learn more about your project and then I can help you contribute. I did this for Pibee, I did this with a lot of different projects. And then I think it was it was quite well because then you can take what you learn and you can implement it later. So the second uh question for that was when um how to structure the documentation, okay? So there's a couple of things you can do. Uh first of all, I already talked about things like templates and the modular docs project and figure out how to store your content to scale. But you gotta ask

Speaker 1: quote unquote potential users uh how their workflow how do they actually use your tool okay and then from that uh common set of tasks that people want to achieve with your tool, this is you can port that back to your documentation. So in a similar way that in bigger enterprise projects We collaborate with the QA testing uh teams. So they build test plans and then we use we leverage that to make documentation. So it's a similar thing, um, whatever you're testing, more than unit tests. So am I talking end-to-end testing. And then you can also research best practices and templates. There are more resources out there for that. And then these last two questions are basically the same. I love this. I don't know what I don't know. So how can I possibly know?

Speaker 1: what you don't know. And that is a great question. And accepting that you have a problem is the first step in solving that problem. So just by and admitting Okay, uh an understanding that different people have different starting points in their knowledge, and just because they don't know what you already know, that doesn't mean they don't know anything Okay. So they might know different things. Um, so reach out to your peers, make yourself available. for training and for mentorship and be kind to the people who want to contribute because welcoming Projects get more contributors. Okay, and that is something that I've seen in a lot of different places, and this is part of why I'm still involved in Django and Python communities.

Speaker 1: uh because you have been extremely welcoming to me, even though I do not write code at all. Okay? And you've you've embraced the different skill sets that are needed to create better software in an open source way. And this is why I'm still here. So if you want to be bring more people into your projects, be nice to them. I know. Uh so and then the last thing I want to say is most or a good percentage of technical writers or documentation-oriented people, such as myself and many peers that I have who are extremely talented writers, we do not have a deeper understanding of how your code is written. Okay, but the strategic communication and the ability to see things on the bigger picture can help your project.

Speaker 1: So you you should respect that and you should embrace that in a collaborative way And we have, I think, maybe a few more minutes from more questions. What's happening on Slack? Oh, time is up. What wait, can we take like where is uh where is our fail? Okay, do we have like a non-weaponized question from Slack? And then so I will just say that if people ask questions on Slack I will read it later and I will answer them personally later. So if we don't get to it now, I will answer it later.

Speaker 2: There's a question about having not much time. Um if you have a software project that doesn't have any docs and you have little time, where do you start? What's the single most important thing to to document or to write?

Speaker 1: Read me. Easy. Read me. You can base it on the template from Write the Docs or something like that, and you have just enough information. It could be a paragraph. Okay, it could take you like a couple hours just to understand what the basics of the project is. Just start with a README.

Speaker 2: Okay, I think the other questions are best left to be answered on Slackland later.

Speaker 1: Yeah, probably. Probably. Okay Let's write some dogs.