 So as the presenter has said, my name is Mason Egger. I'm the lead developer advocate at Gretel. Gretel is a synthetic data company and we can talk about that completely later in the Discord or in the virtual platform. But today we're gonna talk about documentation, specifically how to write documentation that developers will engage with and that they will love. This talk is very verbose. This is probably my most verbose talk because I jam a lot of information in here. So if you would like to follow along the QR code on the screen, we'll take you directly to my slides. They're also on my website, but if you just follow the QR code, it'll take you right there. I'll leave this up for another couple of seconds for anyone who wants to follow along with the slides on my website. Okay, I think, and if you don't, you can just go to mason.dev. It's the same exact title and it's on the homepage. I think it's like the second link from the bottom. So it's a relatively easy slide deck to follow. But anyway, so here we go. So first off, let's talk a little bit about like what is tech writing and why people appreciate it. So I want everyone in here to think about a feeling of that you get when you're following an online tutorial or a piece of documentation and the code works on the first run. Like you just spent 20 minutes working through a tutorial. Maybe it was a digital ocean tutorial. I used to help write those. And the code just works on the first run and you're so excited and you can move on and just think of that feeling when code works, it's a great feeling. Now think of all of the time that you've wasted throughout the span of your careers on following broken documentation, outdated documentation, documentation that didn't work or left out of key vital step and you just didn't know what to do or it just took you forever to actually get through this documentation. And then just think about like what is the difference between these two? What made one of these really, really good and what made one bad other than the fact that maybe one didn't work? Because there are plenty of really good tutorials out there that work and there's some that they still work but it wasn't a very fun experience to work through that specific tutorial or it was more difficult. So technical writing in the broadest sense is just instructional informative writing that focuses on how to accomplish a task using a specific tool. This can be hardware, software, everything in between. Technical writing is not limited to the tech space in particular. This goes across almost anything that has a product. So think of your blender. Whoever writes that manual is technically doing technical writing. So why is technical writing important? Well, it's usually the first impression that someone will ever have with your project. And this is, if you take nothing else from this talk this is the key bullet point I want you to take is that if they don't like your writing or they don't like your documentation or they can't figure out how to use your tool immediately they're going to leave and find another tool. There are very, I can think of very few libraries where that's the only library that does this thing. There's so many open source projects now and so many tools that if they can't figure how to use yours they're going to leave and if they can't figure how to use quickly they're going to leave relatively quickly. But technical writing teaches us about a new code or project that we didn't know about. When was the last time that you found a project just by browsing source code? Like going into GitHub and reading straight.py files. Readme's do not count. If you go into GitHub and you're reading a readme that doesn't count that is technical writing. So technical writing is usually the first step and the first thing that anyone will touch. It also teaches people how to use your project effectively and safely. So imagine you have maybe a vehicle manual or something for your car and the direction say fill up the tire with air versus fill up the tire with air to 35 PSI pounds per square inch. It doesn't seem like it's much but that's a big difference. If you overfill a tire it explodes. That's not a good day. Could seriously injure you. You underfill a tire, you damage your car. So even these minutia of details that you may leave out could have drastic implications for the quality of your documentation. Technical documentation helps you build community around your project. It's likely to bring people back. People will want to contribute. And the thing that I've noticed more often than not is people will tell their friends about your project. If your project is good and the technical writing is good, people will like it and they'll tell people, yeah, not only does the project do exactly what it says but it's super easy to get going. And I never have, I've never confused because the documentation tells me everything that I ever need to know. And that's a great thing and you really want that. So today I'm gonna go over my top 10 tricks and tips for improving your technical writing disclaimer. These are my tips. This is Mason's tips. This is what I've learned after spending multiple years when I was writing at Digital Ocean and now I'm writing at Gretel, working with professional editors and all of these and like amazing people who have taught me so much about technical writing. Just because something I say does it, like maybe something didn't make the list that you think is really important that does not make it invalid. There are so many things that I could have said here. Picking 10 was tough. If I had all the time in the world this would be called Mason's 237 tips for improving your technical documentation. But I had to put it at 10 because I don't think anyone would want to see me rant for six hours about how to improve your docs. If you do tweet at me and maybe one day I'll do a YouTube video on it. I will probably get red in the face and lose my voice by the end of it. So tip number 10, make your end goal clear. Have a clear, concise goal in your documentation in the first paragraph that tells people what they should expect. This library will do X. In this tutorial you're gonna do this and this and you're going to get this. If you're writing a tutorial don't spend the first thousand words of your tutorial telling the reader how great the technologies don't go on a monologue about, this is the history. In the beginning there were computers and then all the way, oh now we have Python. Like we don't need 30 years of tech history. Yeah, okay, I was talking about don't monologue at the beginning of your thing tell people how to get going. It's a very valuable thing for them to do. People already know how great the tech is if they're come, usually how great the tech is they're coming to try out. You don't need to write a novel. The reader is there at your documentation to get something done. They're not there to read a tech novel. Make it blatantly obvious what your reader will have learned, built, accomplished, understood by the end of your documentation. So if you're writing say a tutorial on how to stand up a Django web server on engine X at the beginning of the thing it's just by the end of this tutorial you will have stood up a server deployed Django application using engine X and this will do all these things. Make it blatantly obvious at the beginning what is going on. So, okay, next one. There we go, random thing there. Tip number nine, don't be overly verbose. Technical documentation should be concise. It's not a novel. If you want to write a tech novel go for it. There are quite a few out there and they're hilarious. There are plenty of them out there but you don't need to be using SAT words here or I don't just large overly verbose words that are not very commonly used in the English or in the common language vernacular. All a good rule, a good tip for billing documentation is always assume that the readers of your book do not speak the same language as you that if say if you're running them in English English is their second language. There's a lot of nuances to being a native speaker versus learning another language. So if you always assume that they don't speak it then it doesn't confuse anybody. Like it makes it the native speakers will not have any problem reading it and the people who may have just learned that language so they can, you know, or struggling to learn it or getting to it, they won't struggle with it because you didn't write it in a way that makes it very difficult. Aim for a low reading level. So there are many tools, Grammarly does this. I use something called the Hemingway app and it basically gives you a grade level estimation for what your writing is. So I usually aim for a third grade reading level which is not a very complex reading level. The highest I will allow myself to go is a sixth grade reading level. It's, it allows it to just, it keeps the documentation really simple. You're not wondering what do they mean in that sentence? No, it's do this, this will do this, this is how this works. Don't over complicate it. Tip number eight, use inclusive language. Avoid gender pronouns and go for more gender neutral pronouns. Don't be afraid of using the second person. This is a big debate amongst a lot of people. When you're using, if you're doing a tutorial or something and you're like dictating, you're gonna do something. Next you will install nginx on your Ubuntu machine. Totally fine to do something like that. If you're looking for a second person plural thing because a lot of people will say like, hey guys or something like that. If you're looking for a second person plural, I'm from Texas. I'm coming from you now from Austin, Texas where the temperature has been 42 to 45 C for the last three months, month and a half. So the word y'all is very much in the Southern vernacular and I love it. I even, if you Google my name on the internet and the word y'all, there's a whole talk I give on how you can use y'all in your everyday thing. But I digress. Avoid using internet slang that can be viewed as derogatory. So there's noobs, there's 10X developers, there's dummies. There's a very popular book series of blank for dummies and it's actually a very good book series. I very much like them. But I know people that are like, I'm not a dummy. I'm not going to read that book. So don't do it, don't do it. It's not worth it. You're going to drive some people away from it. Avoid words that can make someone question or doubt their skills. So saying something like something is simple or something is easy is actually, it's a very big turn off for a lot of people. When you tell someone simply install Python from source and they're like, well, that wasn't simple at all but it may be simple to you, but not to them. And you would be surprised how many people get just completely turned off from a project because they're working on the project, they're doing the documentation. People are saying that these steps should be simple. They were not simple at all. And they get, they get in their head. They're like, well, if this was the simple part then the hard part's going to be unbearable. So avoid using words like simple, easy, all of that stuff. You would be surprised how much it really does affect your audience. So tip number seven, limit your technical jargon. Jargon, for those of you that I mean, I didn't know this word until a couple of years ago. Jargon is a special word or expressions that are used by a particular profession or group that are difficult to understand otherwise. Imagine, if you were an outsider standing next to a bunch of tech people talking about Kubernetes, you'd have no idea what they were talking about. You could also still be a tech person listening to people talk about Kubernetes and still have no idea what they're talking about but that's an entirely different problem in and of itself. Overuse of jargon can make it very difficult for beginners to grok your content. Did you see what I did there? I, it took me years to understand what grok meant. I don't like that word. Knowing your audience will help you determine how much jargon you use. So it's not like don't use it at all but if you're, are you writing for an internal documentation for your team then you can probably use a little bit. Like if there are acronyms that are known within your team, then use them because that makes sense. Or if there are certain phrases within your group of the people, if you know who your users are you can then allow yourself to step outside of these bounds. But again, all, if you assume that, assume beginners, if you don't know your audience. So if you don't know who's actually gonna be read it reading your documentation always assume the lowest level and go from there. It will make sure that it's accessible to everyone. Beginners will appreciate you and experts will completely skim over it. They won't even notice it. You can also have a statement saying at the beginning for who your documentation is for. This documentation is for beginner developers who do not know how to deploy Django to a Python server or to a web server. Totally fine doing that. So next tip, tip number six, define all acronyms. Tech has way too many acronyms. We have acronyms for our acronyms and then you get into the recursive acronyms which just, no. We even have some acronyms that can mean multiple things and it's awful. Acronyms scare readers away easily, always. They scared me away when I first was in university doing stuff at the acronyms, trying to learn networking and going through the acronyms. It absolutely terrified me as a new learner. Terrifieders, new learners are always intimidated when they're learning about tech. Everybody is intimidated when you first start learning about tech. If you don't, until you understand how the tech works, it really is perceived as magic. So acronyms feed this fear tenfold. Write out the full name of the acronym when you first introduce it. So for example, you'll need to add a record to the domain name system, comma, DNS, to make sure that you can access your website via www.mywebsite.com. If you plan on using the acronym for the rest of the documentation, say so. Say that you'll need to add a record to the domain name system, DNS, comma. We'll refer to the domain name system as DNS for the rest of this tutorial. That way, if anyone is curious, they can go back up and like, oh yeah, they're just gonna call it that for the rest of this time. You can also define all of your acronyms using the tutorial at the beginning or end and link back to them when you use them. So this is like kind of a glossary kind of thing. This would build it more advanced in the documentation tooling, but it can be done and it's really cool. So tip number five, avoid memes, idioms, and regional language. So this is kind of like jargon, but more pop-cultury. Avoid using memes unless you are positive of who your audience is. Idioms, group of words established by usage is having a meaning not deducible from those of the individual ones. I had a hard time even saying that, but things like pull out the stops, piece of cake, costs an arm and a leg. These are English idioms and stuff that we understand because we've been around them. We speak English. We understand like, it's a native speaker thing. Like you can get them, but like if this again, if you assume that this is someone who's English is a second language and maybe they just got through like certified and being able to speak English. And you say something costs an arm and a leg, they're gonna look at you like you're barbaric because they're gonna think that you're like, oh, we actually have to cut off like an arm and a leg. So don't use them. They really do make understanding it difficult. Your six coworkers will probably understand these. So again, if you're writing internal documentation, totally fine. A global audience who might have never seen SpongeBob might not get your weird SpongeBob memes. Avoid using regional language that might confuse native and non-native speakers. And now we get into the joys of English where performing this command will totally trash your system or don't use this library, it's dodgy. I mean, just the difference between the different vernaculars of English around the world can make it difficult for even English speakers to understand native English speakers have a hard time understanding English. So just don't do it. Try to avoid it, be a little bit more, you know, prescriptive and like, you know, to the point with it. PowerPoint is being weird today. Tip number four, use meaningful code samples and variable names. If I have a run for public office, this is my platform. Use examples of real problems that your code can solve. Readers want to know what problems your code solves. Show them, don't tell them, show them. How many of you have actually read the entire description on a stack overflow problem before scrolling down and just copying and pasting the code? Yeah, I doubt it's everyone in this room. It's also really fun to do these kind of like question and answers when I can't see any of you. So I'm hoping that the jokes are landing. If not, sorry. Very often readers just skip to code. If you have good examples, they may get the entire answer from a single code block and never actually read any of the things that you've written. That's not a bad thing. That's actually a really good thing. Use meaningful variable names. This is the part that I get on a high horse about. We all say coding should be self-documenting. Well, the documentation should be self-documenting too. Foo and bar are useless, they need to go. Period, end of statement. That will be, I will die on this hill. Like use variable names that are actually meaningful to your user. Include everything that is needed to run. This includes all of the import statements. If you need to import something, make sure you show people how to import it because it's not always obvious based on the name of the Python package or anything, how you install it or how you get it to go so that you can use it. And then always have a completed copy of copy pasting. So if you're running a tutorial and you're walking through the user say a basic flask app and you're like, this is how we take our first request, this is how we do this, this is how we run it. Have those blocks separated out and be like, add this to your editor here, add this to your editor here, explain them. But at the very end, have a giant piece of code they can just copy and paste the whole thing. That way if they don't want to do it or maybe they do a typo, everyone does typos. Being able to have a working functioning piece at the bottom will make the experience for your users so much better. Tip number three, we're getting here towards the end. Don't make your reader leave your docs. Avoid sending readers to many other sites and links, mixed up by words there. Everything necessary to complete your task should be in your article. Copying a few steps from another piece of the documentation is better than sending people to other sites. If you're, when people leave, they don't come back. This is a big thing, is that like when you like, how many of you have fallen down a Wikipedia or a Reddit rabbit hole? Or some sort of rabbit hole where you're Googling this, like, oh, I don't know this, now I need to go here. And I don't know, oh, I got here and I don't know this, I need to go here. Basically, yak shaving. We've gotten all the way down and people don't pop back up the stack when they're doing it. They just, they never make it back to your site so it's not a good experience for them. If you're going to make your reader leave your article, have a reason and then have a way to bring them back, do it at the beginning. And then have like a, you can have like a list of prerequisites at the very beginning of your tutorial that needs to be completed before the tutorial. So you can see something like you need to have Java installed on this server. Here's a link to install Java. Once you're done installing Java, come back here, follow this next step. Yeah, make sure you link out directly to what they need to accomplish. Don't say go install Python. Like that will, you'll never get them back. If you're like, oh, just go install Python. You'll never get them back. Give them a tutorial, give them some sort of way of showing them how to do it that sets them up for success and then have them come back when they finished. Another, a great tip about this is is if you tell people how to set up their environment, then you have control over the environment. So when you're writing your documentation, your testing, it's not as difficult to know what's going on in their environment because you showed them how to set up the environment. So now you're not like, oh, we'll do that. Maybe they had some background libraries installed but we know they don't because we said use this virtual environment with this version of Python. And it's a great way to make sure that your docs can remain consistent because if you have to try to debug every single way that someone's ever installed Python, your documentation is gonna be a novel and it's gonna be huge. Tip number two, make your content scannable. Make it easy for readers to find a single piece of information. Beginners tend to read entire posts when they're doing it. While experienced users will scan for the information they need. They'll go to a specific heading or a chapter in the tutorial. Oh, I just need this piece, let me get it. Use headings and subheadings to break up your content. Don't just write one long thing. Step one, install Ubuntu. Step two, install Nginx. Step three, install Django. Step four, write Django app. Step five, deploy Django app. This will at least break it down in a way that if someone who does want to scan it can find it immediately or if a beginner read this whole tutorial and then comes back at a later date because they just need to remember how to do one thing, they can easily find it without having to scroll through or do a control F and find some phrase that they remember in the tutorial that was kind of near where they wanna go, make your content navigable. Outlining big changes such as a next step or a change of context. Pairing of the table of contents, my favorite thing to do, so much nicer. Use consistent style when you're writing. For example, make all your library names bold and then all your file paths italic. The user will quickly pick up on this. Humans are great at recognizing patterns. They're really good at like, oh, every time I see something in bold, that was a library name. Now I know that, so now whenever I see it, three tutorials into my documentation later, I know that it's bold. I know that's a library. We're really good at this and we pick up on it subconsciously. So do this and your experience will go through the roof because people won't even know that you're guiding them to where you need to guide them to that they will appreciate it regardless. Consistency is key. There's a lot of really good style guides. DO.co slash style is the digital ocean style guide and it's the one that I use. You don't have to just be consistent. If you want to make up your own style guide, fine, as long as you're consistent with it, then it's not a problem. I would probably air against flashing text and marquees. This isn't the early 1990s. Other than that, everything else is pretty much fair game. Tip number one, verify your instructions. Test, test, test. Always verify that your instructions work and test them. Test them again and then test them a third time. The only thing worse than no documentation is incorrect documentation because when it comes to no documentation, I either figure it out or I leave and go find another project. When it comes to incorrect documentation, I may spend an hour wasting my time and now you've wasted my time and in my mind, time is honestly the most valuable resource we have. So wasting someone's time is actually in my mind worse than not giving them instructions because they'll either decide to power through it and read the source code or they'll go find a project that actually does give them instructions. If possible, have someone else test your work. You would be like, you're going to get biases and stuff. Like you're used to seeing this code. You're used to working on it. You know that this works this way and you may not even know that you know that and you're going to make assumptions and stuff that the common reader will not. So having an editor, a peer, a teammate, even a friend work through documentation can help you find lapses and where you were missing. The other option there is to be able to put yourself into a beginner's shoes and pretend you know nothing about the project. That's still very difficult to do. Like you fighting your preset biases and knowledge of the project makes it difficult to do this. It's not saying it can't be done but it is a very difficult thing to do. And if you miss, you make a mistake there. It's really difficult to figure out why it's not working, why it's not resonating because you're automatically making an assumption. Use a fresh environment for your testing, please. Attempts to remove bias from your development environments. You don't need like your shortcuts, your packages, your tools, everything that you have on your work station it makes it work for you. So spend up a small VM, spend up a fresh virtual environment. And even then, if there's stuff in the system Python path that could mess it up or other command line tools that you have that other people don't, maybe you have HTTP IE installed, which I love. And you just never think about telling people to install that but all of your documentation uses it and they go to type HTTP and it just does command not found and they have no idea why because you didn't think about it, understandable. So fresh environment, it really does make a difference. Bonus tip, last tip. The best way to get better at technical writing is to write like everything on earth, practice makes perfect. Like you have to do it to get better. You get better at coding by writing code. You get better at playing a musical instrument by playing a musical instrument. You get better at writing by writing. It's relatively straightforward. Set aside a set amount of time daily, weekly, monthly. Doesn't matter. If you really want to get better at your technical writing, find time. You do not have to publish it. You don't have to publish anything you write but don't throw it away. Save it in a folder. You never know when you might want to dust it off. You never know when maybe you wrote something like, oh wait, I already kind of like started this. Let me go get it out of my folder that I keep everything in. It's whatever it is. So just practice. It really will get you really far. How can you get started in technical writing? Well, write documentation at work. There is always something to be documented and honestly it usually leads to promotions. Every time I've ever been promoted while I was in engineering, it's because I got into a project, realized the documentation was awful and then while also working on the code and stuff, wrote myself tickets and improve the documentation and it's always made a great impression on my bosses. People love when things are documented but nobody wants to document it. Start a blog. The best part about blogs is it can be a freer medium. You can write tutorials. You can write blog posts. You can write recipes. It doesn't matter. Write whatever you want. It's great for practicing. Contribute to open source projects. Many open source projects need help with documentation. If you can honestly tell me that every open source project that you've ever worked with has perfect documentation, then you don't need to do this. But I do not think there's a single person in this room that can say that to me with a straight face and not bust out laughing. So help them out with it. Hacktoberfest is a great place to start. This is how I started every year. I contribute documentation every year. Yes, I like writing code. It's pretty fun. But more often, there are a lot of people who want to contribute code and do a lot of stuff doing code. There's not that many people that want to contribute docs. So I help people with their docs because I want to try to have a big impact. If I don't fix that bug that's there, someone else will fix it. But maybe someone else won't write the documentation. So thank you so much. That's all I have for this time. We had a weird technical difficulty, but that's totally fine. Follow me on Twitter if you want to ask me some questions or anything. I'll try to get into the platform and see what's going on. Also, if you scan this barcode and you want some of this synthetic data sticker right here, scan the barcode, fill it out. I will, we will mail you some swag. And if you want, again, these slides are on my website. Thank you very much. Hopefully next time I can be there in person with you wherever the next Euro Python is, but I hope you're all having fun in Dublin. Wish I was there. Thank you so much.