 Okay. Perfect. So I'm Alana Burke and this is, documentation is like a plant. You need to tend to it. So I work at Amoezi IO. I do documentation training and developer advocacy. You, my pronouns are she and her. You can find me on Twitter and Drupal.org at A Burke 626 or on Slack at Alana Burke. So the biggest question that we have is why is documentation important? So when talking about documentation, I find that people tend to fall into one of three camps. People who are just as enthused about documentation as I am and want to write all of the things. People who are enthused about documentation but don't know how to fit them into their current workload or how to convince others. And then there's people who don't think that they're important. I think this talk will have something for all three of those people to take away today. So let's get down to why documentation is important. If your documentation is not good enough, people will not use it, no matter how good your product is. And if people don't use your documentation, they're less likely to use your product because they won't know how. This is especially true if we're talking about something technology oriented like a hosting platform or an API. If you've built something, presumably the goal is for people to use it. So let's make sure that happens by documenting how. Let's talk about a few types of documentation and the things that we are referring to when we say documentation. One type is inline code comments. Well documented code is always important, whether it's being used to generate API docs or not, keep it up to date. Release notes. These are a great place for folks to get an idea of what's going on with your project and what has changed. Readme files. These are often the first thing that people read or see as designed. So make sure it's got what your users need to know. And of course, we have external documentation pages. These are what we most often think about your user facing documentation pages. You may also have videos, slides and all other types of training material. One of the key parts to establishing and maintaining good up to date documentation requires creating a culture of documentation within your organization. So what does this mean? First, get everyone on board. You can't get your clients to prioritize documentation if your whole organization top to bottom doesn't prioritize it themselves. Document everything. Get in the habit of documenting absolutely everything that you do from internal processes to client information, just document it all. And make it easy. Set up templates to remove barriers to writing docs. If documentation is easy, you'll be able to get your team to pitch in. Even with a dedicated documentation writer, like in my case, I still need the engineers to document what the product is actually doing. They don't need to give me anything fancy or even anything written. We can just chat. But at the end of the day, they're the people with the knowledge and I need to get it from them. If they're willing to write it, that's even better. I want to make it easy for them. So take a look at your workflow. Is it a huge pain to submit changes to your documentation? If it is, how can you change that? And finally, begin it for the long haul. Documentation is not a one-time project. It's a living document that changes our time. It needs constant attention and love. If you go in with the mindset that you're going to write your documentation and be done with it, you're going to be unhappy. Good documentation is never truly finished. Another thing to help foster the culture of documentation is to make sure that you have a good relationship with your subject matter experts. Sometimes we see a negative relationship portrayed between the person who wants the documentation to be written and the person who has the information, but it doesn't have to be like that. Here are some things that you and your engineers are on the same page. Learn the language of your engineers so you can learn to speak it to them. Do your homework on the software before you sit down to have a conversation about documentation. Familiarize yourself with the terminology of the product. For example, I was a web developer before I switched over to this job doing documentation, but I didn't do DevOps. So before sitting down to talk about Kubernetes and all of the things that our engineers were doing, I had to catch up and make sure that I knew some of the terminology so that I wasn't constantly asking them to define things while they were trying to give me an overview of something more complex. You're also going to need your engineers to QA your work for technical accuracy, so establish a workflow that works for everyone. The next major part of creating a culture of documentation is establishing ownership of your documentation. This is the best way to make sure it doesn't fall by the wayside. Ideally, you have someone on your team who is a technical writer and is managing and writing the documentation as part or all of their duties. If that's not feasible, take a look at your team and their strengths available time and willingness to take on the task. This person is not responsible for just writing the documentation but managing it and assuring that changes are made in a timely manner. This includes receiving and integrating feedback. Most teams will find it easiest to use whatever ticket system they use in code to track needed changes or additions to documentation as well. Determine a process for updating your documentation. Will it be revised on say every minor release or just ad hoc when something to update? Will you check on certain parts every so often to see if something needs to be updated? How will you organize tickets and issues? So what I do is I have an overarching documentation epic in JIRA so that I can see all of the related tickets, everything that has to do with documentation because they're not always assigned to me. Sometimes I create them and assign them to other people. This way I can keep an eye on all things documentation. How to get buy-in from stakeholders. This is a really tricky one especially in places like government where budget can be short. Some clients or stakeholders push back on documentation as something extra. Anything that takes time costs money. A documentation is often seen as something that can be cut from a project to save costs or done later. How can you convince them otherwise? Good documentation brings in users and customers. Documentation helps to not only interact with your, helps users to not only interact with your product but can serve as a marketing tool. Bad documentation is just the opposite. Bad or missing documentation turns users and customers away. Without documentation or with frustrating documentation, you risk losing or off customers. Good documentation shows that you're thoughtful, that you've worked through these issues, you've provided solutions and that you care about your customers. Keeping everyone informed avoids a crisis later. When you and your client have everything you need to know written down, there's less chance of an expensive crisis later that no one knows how to solve. And keeping track of changes helps track down bugs. Documenting changed one of troubleshooting and can cut down on time and costs. Getting clients involved. When developing a product and documentation for the client, keep them involved. Make the documentation a regular deliverable along with your code. This gets them reading the documentation, reviewing it and making sure everyone is on the same page from the very start. Develop a plan for managing and maintaining the documentation after the project is handed over to the client. That way, when the final handover is done, the clients have already reviewed all of the documentation. Hopefully they've asked any questions that have arisen and now they're ready to take the helm. Now they'll be less likely to break things or to need emergency support. Let's go over some ways to get started writing your documentation. First, define your audience. These are just some common examples and your audiences may vary based on what you're developing. A user, an end user of your system who won't be involved in managing it in any way. A developer, someone who will be building and maintaining the system. An administrator, a user who will be managing the system but not coding and maintaining it. So if you can sit down and define these audiences, it will help you better define your documentation and better organize it. Answer the basic questions. As you're fleshing out your documentation, use these questions. You use them to write just about anything and documentation is no excuse. So who is the product or system for? Why are certain things done the way they're done? When would I use this? What does the product or system do? How does it work? Where can the user find the information that they need? This might seem super basic, but these are actually really helpful ways to sit down and structure your documentation. There are many ways to have bad documentation, but here are some common pitfalls. Incomplete, missing steps or information makes your documentation useless. I am sure that everyone here has started down some sort of tutorial to install something or do something and only gotten halfway through to discover that it's incomplete and now it's completely useless. None of the steps that you did mean anything because you can't finish it. Or out of date. If your documentation doesn't match the latest version of your code, it won't help users. Just like in the previous example, you've gotten halfway through, but it was for a previous version of the software. And now, again, it is useless to you. It does nothing. It doesn't help. Inaccessible. If your user can't find it, they can't use it. I've given talks on accessibility before. This isn't one of them, but your documentation needs to be just as accessible as anything else you would put on the web. It also needs to be inclusive. Ensure that your language is welcoming to all. If you are using language that is off-putting or insulting or isn't readable, then people aren't going to be able to read your documentation. They won't be able to use it. And again, that makes bad documentation. Other common pitfalls include making your documentation hard to read. For example, not using white space and creating walls of text. I have seen some examples of documentation being made available as content that can't be updated, like PDFs. And once a PDF is out there, you can't take it back and you can't update it. So that's another really terrible thing to do. So let's talk about some things you can do to improve your documentation right now. Without your red pen, go through and note anything that is incorrect or out of date. Slim accurate documentation is better than having lots of documentation. Define your audiences. We just went over this. Who are you writing for? Figuring this out now will make it much easier to target and organize your documentation. Nail down the basics. Most of your users will need your basic getting started info, how to install your software. Make sure you have that complete before moving on. Plan out a taxonomy. When you're writing new pages for your documentation, where will they go? Take a look at the information that you need to break down. And plan out your information architecture so that for each piece of content you create, you can answer, where does this go? And take a look at the design. People naturally prefer to read things that are pleasant to the eye. Make sure you don't have long paragraphs where a list will do. Use images and screenshots were indicated. Make use of white space. Choose styling that is modern and attractive. Again, you want people to read this. And finally, there are no shortcuts to good documentation. Take it slow. Documentation is a marathon. There are absolutely no ways around it. You can generate documentation from your code comments, but that's no substitute for actual written instruction from a human. It's just part of your documentation ecosystem. And I've included a couple of resources here. Right The Docs is an amazing community for all things documentation. They have a Slack channel, a newsletter. They organize conferences around the world. And I've also got another link here to technical writing courses from Google. A lot of people, the main question that I get is how can I be a better writer? How can I become a technical writer? And these courses look very in depth and very informative if that's something that you are looking to improve on. So let me take a look at the questions over here. Does anyone have, I don't see any questions in the chat. Does anyone have any questions? Thanks, Alana. There was just, we're having a few technical issues with the live Q&A one, which we're trying to sort out. We did have a question from Griffin about a favorite documentation tool and platform. So you had any thoughts on that? I am currently a very big fan of Gitbook, which we just moved our documentation to. It still allows us to use the same kind of Git workflow we were using that a lot of people use like writing our documentation and markdown and keeping it alongside our code. But it also on the other end gives us a WYSIWYG that we can update so that I don't have to push and go through an entire pull request just to update a typo. So that's something that's really lowered the level of effort from minor documentation updates while not actually interrupting the flow that everyone in our company is used to. And Gitbook also is, it'll, you can get a free account for open source projects, which is really fantastic. If you just contact them, I'm not sponsored by them. This is not a Gitbook commercial. I just really like them and we've had a lot of success using them right now. And they work really well just for our particular use case. Okay, if there's other questions, just while we're sorting out the issue with the live Q&A, if there's anything that you want to put through the discussion forum, we can put that in quickly now. I did have a question in terms of, I guess, one of the things is that you mentioned there was something that's very easily cut out of a project when, you know, particularly governments are looking to save costs. Are there any other techniques or tips in terms of trying to convince people not to do that and the value of that? I mean, I think one of the big things is just showing how it's going to save costs later. The more you know about the project, the more everyone knows about how it works, the more, you know, everyone on the team is empowered to fix things and change things and do it themselves. You know, crises are inevitable in tech. Things will break. Things will blow up horribly. It will happen. The more that everyone is informed and everyone has ideas of how it works, the less that it's likely to boil down to some very important crisis that, you know, one or two people can solve. So if everything is well documented, if everybody, you know, knows how things work, then it becomes less of a crisis and more of a, oh, hey, let's check the documentation and see if this is something that we know how to fix. And I think, especially for government, I think that if you can convince them that this is going to save money in the long run, I think that that's a really good tactic to take. Yep. And just another question in the discussion one from Fraser about using screenshots and videos. It's a really good question. What's your thoughts on that? I say use screenshots when description of the screen is too, you know, it gets too difficult. Or I also sometimes just use them as an addition to, you know, kind of mix it up, make it more attractive, but also keeping accessibility and knowing that if you can't describe what's going on in the screenshot and that's not accessible. So make sure that whatever you're doing with videos and screenshots are described or closed captioning or doing, you know, adding a transcript and making sure that everyone can use those. I do see places where screenshots are very much overused and keeping in mind that, you know, if the UI changes, then you have to update those screenshots, but I think screenshots can sometimes make things a lot a lot easier for people than just reading a wall of text. And same with videos, some people really love to learn by videos, some people hate it. So as long as you have that content available in another format, I think it is fine to release videos, but also being aware that you have to update those should anything change. Well, that about wraps it up for this session there. There was a question about making a slide deck available for this. I don't know if that. Yeah, perfect. Thank you very much for that talk, Alana. That was fantastic. And I guess it's a call to everyone to go out there and keep that documentation leaving. Thank you very much. Have a good one. Thank you, everyone.