 All right, well, let's get started. This is documentation as a deliverable, the business case for documentation. You are at Drupal Comportland. I hope you know that by now. This is A106. I'm Alana Burke, and I work for Amazie IO. My pronouns are she and her. At Amazie IO, I do documentation, community management, and developer advocacy. And just a little bit about my background, because I think everyone comes to documentation from a different place. I always find it interesting to find out what your background is if you do documentation or technical writing. So I spent 10 years as a web developer and a Drupal developer. And I have a BS in information science and technology. So we're going to talk about a handful of things today. But mostly, we're going to talk about why is documentation critical? What actually makes it critical to a business? We're going to talk about how to get buy-in when you are trying to explain to someone why documentation is critical. And then we're just going to go over briefly a couple of best practices when trying to get documentation done, when trying to convince someone that documentation is critical. But first, I would like to talk about some documentation myths and why docs don't happen. So one of the myths that comes up most commonly is that documentation simply isn't important. It's not as important as getting the code or the project itself done. You might hear that the project will be self-explanatory when it's done or that the code is commented, and that's enough. Maybe someone will insist that the code is written just so well that it doesn't even need to be documented, that anyone will be able to understand it. And even if it were true that the code was written in the most elegant and readable manner, even if the code comments are impeccable, it's not the same as user-facing documentation. Documentation is critical to any project. And also, those close to a project, especially when you are the one working on it, you can become overconfident. When you are the one who's created this project, when you are the one with all of the domain knowledge, of course, you're going to think it's simple, straightforward, easy. Think about that outside the realm of tech and work. You're probably an expert in something, and sometimes you're surprised when other people aren't familiar with things that are basic to you. For example, I have been taking care of and rescuing animals my entire life since I was a little, tiny kid. And sometimes I'm really surprised when people don't know, for example, the benefits of spaying and neutering your pet or why you should do that. But that's because I'm an expert in that domain, and it seems obvious to me. So keep things like that in mind when you think that someone else might easily understand something that you are an expert in. We'll talk more later in the presentation about why documentation is important in a business context. But the main reason is so that other people can understand what your project does and how to use it. The next myth that I hear a lot is that there isn't time to write documentation. My answer to that is that if you don't have time to document what you're creating, then you haven't allocated enough time to complete the project. Find the time and carve it out during the planning phase. If you have time to code the project, you can find the time to document it, because it is every bit as critical as the code. Later, we'll talk about some strategies from making sure there's time for docs. And the last myth I often hear about documentation is that there isn't anyone to write it. This can be a major pain point on a team. The engineers who create the project don't always have the technical writing skills to write effective documentation. And others on the team who do have great writing skills may not have the technical knowledge to craft effective documentation. And of course, everyone has their own jobs to do and may not have time to get it done. And this is different from there not being time in the project for the docs to be completed. There are a lot of benefits to hiring a technical writer, and I don't just say that because I enjoy being employed. Even if you don't have enough full-time documentation work for someone to write docs, they can often do a variety of related work, as I do, like trainings, demos, client onboardings. There are a lot of tasks that can be done very well by someone with the specific skills that make a great technical writer. So with those myths out of the way, let's talk about what documentation actually does. So the first goal of documentation is to educate. Users should learn from your docs. Good documentation guides users through a process, explaining everything along the way. Be aware that it educates not only your current users or customers, but your potential users or customers. We're going to assume here that we're talking about public facing documentation. Documentation also enhances. One major enhancement can be your product support. When you kick off a product with comprehensive documentation, your support team has a leg up, resulting in happier customers and faster resolution times. And finally, documentation increases. It can increase the use of your product, the use of product features, and even increase sales. The more knowledge your current or potential customers have available to them, the better the chances that they will use or buy your product. They certainly can't buy anything that they don't know about. So give them all of the information. So what makes documentation critical to a business specifically? There are so many reasons, but we're going to go over a handful of key reasons that you can focus on. The first one, which we kind of just alluded to, is marketing. Everything that you put on the internet about your product is marketing. And it's either making a good impression or a bad one. Take this opportunity to show off your product and what it can do. Make your documentation shine. Make it attractive and readable. Make it easy to find, easy to navigate, easy to search. Make sure your product's features are easy to find. Think like a user or customer who might be scoping out your product and wants to know if it can do X and how difficult that might be to implement. If they can't quickly find out that your project easily integrates with X, they'll likely move on to the next thing. Next up, product support. Having robust documentation instead of starting from scratch can make a world of difference. It also helps to educate your support team on the product and how it works. Naturally, your support team will have their own playbooks and likely internal facing docs. But many questions posed by customers are often things that are in the documentation. Knowing that and being able to quickly reference it will help your team immensely. The next one is a big one, thought leadership. This kind of goes along with marketing. You're very likely competing with other companies in a similar face. Show people why they should choose you. You can do this with other kinds of marketing, of course. But technical stakeholders appreciate things like excellent documentation. This is one that I focus on a lot as an example because there's a lot of competition in the hosting world. Just look in the expo hall. But we're all doing things differently in a way that we think is best. So it benefits us to make sure that we're showing everyone, hey, look, we have really smart people doing really cutting edge work. So take a look at our documentation to see what we've been working on. And fourth, we have product visibility. As I said, everything on the internet is marketing. The more docs you have, the more content you have online about your product. This is not an invitation to inflate your docs, but simply to ensure that your documentation is thorough. Just like your product site or your blog, this is another place where SEO comes into play. So take advantage of it. The next reason the documentation is business critical is efficiency. Good documentation prevents wasted time across the board. It can answer questions posed by potential customers, potential employees, current users, current customers, sales folks. Just about everyone who interacts with your product can find answers in well-written documentation. From what features you support to how to install and get started with your product, you can put a lot of information into your docs. And it can be a great resource for a lot of people and save time that might otherwise be wasted searching or trying to find out who in the company knows the answer to this question. Similarly, productivity is increased when folks don't have to spend time searching for answers and troubleshooting because the answers are already there. One section that I really like to put in documentation is a frequently asked questions with common troubleshooting questions. And keep updating that as common issues crop up. So this becomes a really handy reference and allows for more time spent on developing or solving more complex issues instead of explaining how to troubleshoot the same issues over and over and over again. And lastly, good documentation helps with employee onboarding. New team members will much better understand how the product works if they have well written and comprehensive documentation available to them. And this is important not just for support or engineers, everyone working to support a technical product can benefit from reading through the documentation to get an idea of how things work, what technologies are used, what the troubleshooting pain points are and more. Without documentation, this becomes domain knowledge that lives in the brains of your employees and it has to be extracted by each new employee in turn. This takes a lot of time and a lot of effort. I'm certainly not trying to automate onboarding. Everyone needs one-on-one interaction to learn how to do their new job, but good documentation can be a huge help. Next, we're going to talk about getting buy-in. Another really fun part of going back to in-person conferences is that people get to watch you take a drink of water. So now you know why documentation is important and what it can do for you and your business. So let's talk a little bit about how to get buy-in from your stakeholders. The first step is to determine your audience. Who are the stakeholders? Who are you convincing? Where are you getting pushback? Is it coming from your company internally? Or is your company having trouble convincing clients that documentation is essential when it comes to their projects? Are you working with technical or marketing and sales folks? Knowing who your audience is will help you to better tailor your pitch. Next up, you need to build trust. Don't come at this from an antagonistic viewpoint. The success of this pitch for documentation will benefit everyone. It can be really frustrating when you get pushback on something that you know is essential, but listen to their reasons, acknowledge them, and figure out how to address them. If you're dealing with internal stakeholders, you can build trust by doing excellent work, advocating for your clients while showing your work and research into how documentation will help the business. Make sure that you show that this isn't just your pet project, but a business essential. Ensure that you communicate clearly. State the goals of your pitch for documentation and what the benefits will be. If you're stakeholders like numbers, bring them numbers, slides, charts, whatever you need. Do your research. Bring what you know about the stakeholders, what you know about the business and the product, and what you know about documentation, and put it together in a format that your stakeholders will understand and appreciate. Know their preferences. Do they like video calls, email, Slack? Make sure you're putting your best foot forward and making this as easy for them to assess as possible. Another key step to getting buy-in is collecting data. What have you been doing so far? How has it been going? What have the results been? Is there a measurable impact? Is there wasted time you can add up? Lost sales? Think about the data that you can measure here and look for it. Collect it, measure it, and present it. A lot of stakeholders respond best to numbers, so bring them. Maybe your support staff spends a percentage of their time telling customers the same thing over and over and over. They could be easily documented. Maybe you offer a feature that just isn't selling because customers don't understand it or because the technical stakeholders don't have enough information on it because it isn't documented. Look for these things so that you can point them out. Talk to different people in your organization to help gather this data. Can your sales folks help point out where they think a weakness is and where documentation might bolster more sales? What about marketing? Do they think that better documentation might give them a boost in SEO? Find these things out. Once you have this data, identify the concerns. What's the major issue here? Is it that your clients don't know how to use your product? Do potential customers not understand exactly what it is you do? Do new users have trouble getting on board and installing your product? Find the concerns, the pain points that documentation can address. Again, talk to folks across your organization. Find out what the impact is of not having this documentation. And see what others might envision so that you're meeting everyone's needs. And then finally, build your desired outcomes. Look at your data, look at your concerns, the input that you've gotten from everyone else in your organization and put it all together. What is it that you actually need? What does this solution look like? Figure that out and that's what you present to your stakeholders. These steps for buy-in can be applied to just about everything that you're working toward, of course. Though some things are more or less measurable, which can affect how you go about it. So now we're gonna talk about some ways to get documentation done. And one of them that I like the most is documenting as you code. And this is one of the best ways to prioritize documentation, so let's talk about it. First, let's talk about what I don't mean when I say document as your code. I'm not talking about inline code comments. You should absolutely comment your code thoroughly. But that's a different thing and here I'm talking about external documentation. I'm also not necessarily talking about developers or engineers writing docs. While they do have the knowledge, we talked a little bit earlier about that they are not necessarily the people with the best skills to explain that knowledge well in writing. And their time is often best spent doing what they do best. What I do mean by document as you code is that documentation deliverables are created and delivered alongside code deliverables. As each feature is developed or released or delivered to a client, the accompanying documentation is written and published as well. Instead of waiting until the end of the project or some random time after the project is complete, this ensures that everything is documented while it's fresh in everyone's mind and it's done in manageable chunks. One of the reasons that documentation can seem so daunting and impossible is that if you're starting from scratch, it is daunting and impossible. Even if you have all of the knowledge that needs to get out of your brain and into a format that other people can access. Imagine, for example, that Drupal had been developed with zero documentation and you had to sit down today and just start documenting it and not finish until you were done. No one would want to do that, right? No one would want to do that. That's horrifying and you'd probably never finish. And even if you had all of the knowledge in your brain to document Drupal from start to finish, you would forget things or you would leave things out. There's no way that you would document every single piece of it just from your brain. You'd be so much less likely to be accurate or to have access to all of the people who wrote each part of the project in the event that you needed them to explain something or help you out. So documenting as you code avoids this. You're documenting it in the moment while all of the key players are still in play. Questions can be asked, things can be fixed and doing it one piece at a time ensures that everything is documented and nothing is forgotten. The other thing that's important for documenting as you code is technical writers working with developers and engineers. Everyone collaborates best in a different way so I won't recommend any particular way here but when I need to get information about a new feature to document, I work with the engineers who primarily built the feature. I ask them to get me the info however it's easiest for them. Whether that's them making an outline or notes or a rough draft from them, a call with them where I take notes or even them making a quick demo video showing how things work and sending that to me. Anything that fits into their day is fine with me and it gets me started documenting the new feature. I also ask them what's the best way to follow up with questions. My goal is to get the documentation done in a way that takes as little time from everyone else as possible and then finally I want to talk about some best practices for getting documentation prioritized. The first one, as we just mentioned, is making it an actual deliverable. Whether you're delivering to a client or developing an internal feature, make sure that the documentation is expected to be produced along with the code. Next up, put it in your contracts if that applies to you. If you're having trouble with clients pushing back or you feel like you never get enough time to write documentation for clients, stop worrying about trying to convince someone of it during the project. Make sure this is something that you actually put into your contracts along with all of the other things you're going to deliver. You're going to deliver this documentation along with the code. And then finally, have a dedicated docs writer. As I said, this might not be all of their work. For example, I'm our community manager and our developer advocate, but it should be a part of someone's job description. Not just something that gets shoved around from person to person where there's time or something that, oh hey, maybe the marketing team can do this because they're good at writing or something like that. Make sure that you have someone on the team whose skill set matches this and they're dedicated to doing documentation. Hey, I went a little quick today, but that's everything that I have for you. And I am super happy to answer any questions. Hey, we've got a question back here. Yeah, so the question was about putting documentation online and issues of like privacy with client websites. So this is something that we actually kind of balance a little bit at Amazio. So we have our very much public facing documentation that's about Lagoon, which is our open source project which is what powers all of our deployments, right? But then we have Amazio which does, that's our sort of actual hosting company that uses Lagoon to provide services for clients. So then that's where some of the internal documentation comes in. So we make everything public that can possibly be public and then if there's things that our engineers need to know that no one publicly needs to know, that's the stuff that we keep internal. That's the stuff that's like in our internal complements, our internal documentation. But everything else, especially since we do open source, we're obviously keeping all of that public. But everything that we can keep public is public and we take the most minimal things. And there's even some places where we put stuff in the documentation and then we say like, if you're an Amazio customer then you need to talk to your support person about this particular value here and things like that. Does that help answer your question? Okay. Over here. So the question was about whether video documentation is something that you should include. We actually do include some video documentation because I know that some people learn really well that way. So I've done a bunch of things where like we have our little FAQs and then I did a series of like eight or 10 short like two minute videos about like, how to do these things? How to do this little thing? How to do this little thing? And I think those have worked really nicely. I know everyone learns kind of differently. Like I for one, I can't stand video documentation. I don't want to watch an hour video about how to do this thing and what you just tell me so I can read it. But I know other people are like, I don't want to read 10 pages about this just show me a video so I can learn how to do it. So I think there's a lot of balance and just understanding that everybody learns differently and trying to provide that for your clients. So I would also, that's a thing of like, talking to people who's using your documentation, what are their needs? So if we had someone that came up to us and was like, oh, you have all this documentation but I would understand it so much better if you put out a video. I'd be like, all right, cool. Well, I'm gonna put out a video then. Videos in particular are a lot of work. So I think a lot of people don't tend to put those out first and they sort of, it's a thing that you wait until you have feedback, which is understandable. But I think doing things like small videos can be really helpful too as just a sort of, I liked it because it sort of spiced up our documentation a little bit. You know, it was something a little bit different. It was something that we could kind of put out on social media too to say like, hey, here's some cute little documentation things that we did that you can learn about and it's a little more engaging than being like, you know, you don't really tweet out like, here's a fun page of our documentation. Don't you just wanna read about how SSH works? But if you tweet out like a little video then that's something that's, you know, it's got a little bit more of a hook to it and people are more likely to click on it and watch a minute long video. Also, I didn't recognize you with your hood up and your mask and I just pointed at you like I didn't know you. I'm sorry. Any other questions? Well, I, oh, we got one right here. I mean, I think a lot of it would be making sure that you are aware of your own, like your own domain knowledge and that how confident, you don't realize how confident you are in your own knowledge because you're the people who wrote it. I mean, my advice is still really, really, really hire someone else to do it and find a place in your organization for that person. But if you must have your developers do it, make sure other people are reading it. Have someone else, if it's, if you don't have anyone but developers in your organization, have someone else read it. You know, have someone else proofread it and be like, okay, I could follow this. I understand what this is doing. Like I have even had, you know, stuff that I've documented that was, you know, for like outside of a company or, you know, I didn't have anyone to proofread it inside of a company. Like I've had my mom read technical documentation for me just to be like, can a random human on this planet read this and understand what I'm saying here and not to be like, oh, moms aren't technical, but like, no, my mom was really smart and I want to know that just people who aren't in my field can read this and say like, okay, no, no, no, this makes sense. So just be aware that like you're the expert who's writing this, but you're not writing it for other experts or they wouldn't be reading it. Darren. Yeah, always give you a bag. And if you're writing it down steps, have someone else run through your steps. Like a lot of time our product owner will put together or like a whole list of steps of how to do something and then I will do them and I will be like, Toby, none of these work. Any other questions? Hey, well, you can find me on Twitter at aburk626. You can ask me any questions and I will make sure to put these slides up wherever we're putting slides up these days and I'll also share them on Twitter. So I'll give you a little bit of your time back for the afternoon and thank you for coming.