 So, let's get started. So this is, documentation is like a plant, you need to tend to it. So I am Alana Burke. I work at Amazie I.O., doing documentation, training, and developer advocacy. You can find me on Twitter and Drupal.org at aburk626 or on the Drupal Slack at Alana Burke. And Amazie I.O. is also very, very proudly sponsoring that camp. We're very, very happy to do that. So, one of the big questions is, why is documentation important? You know, 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. Then there are people who are enthused about docs, but don't know how to fit them into the current workload or convince others. And then there's people who just don't think they're important. And I think this talk will have something for all three of those people to take away today. So, why is documentation 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. And this is especially true if we're talking about something technology-oriented, like 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 to use it. And yeah, Benji said in the chat, an undocumented feature is a bug. That's completely true. So, let's talk about types of documentation. And there are a lot, but these are some of the main things that we have when we're talking about documentation. So, we have 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. You have 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 exactly what your users need to know. And hopefully, not a whole bunch of stuff that they don't need to know yet. And then, your external documentation pages. And this is what we most often think about, your user-facing documentation pages. You might also have videos, slideshows, other types of training materials. This is all your documentation. 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? Get everyone on board. You can't prioritize, you can't get your clients to prioritize documentation if your whole organization, top to bottom, doesn't also prioritize documentation. Document everything. Get into the habit of documenting everything. Internal processes, client information, etc. So, once your whole organization is in the habit of this, it's going to be a lot easier once you're looking at, hey, how do we document this technical stuff? How do we document this client stuff? And finally, make it easier. Do things like setting up templates to remove barriers to writing documentation. If your 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. I don't need them 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? How can you change that? And finally, be in it for the long haul. Documentation isn't a one-time project. It's a living document that changes over time. It needs constant love and attention. If you go in with the mindset that you're going to write your documentation and just be done with it, you're going to be unhappy. Good documentation is never truly finished. Another thing I want to mention is to make sure that you have a good relationship with your subject matter experts. Sometimes we see sort of a negative relationship between the person who wants the documentation to be written and the person who has to write it. But it doesn't have to be like that. So, some of the things you can do to make sure you and your engineers are on the same page. Learn the language of the engineers so that you can use it to speak with them. When I first came into Amazio, I had been a back-end Drupal engineer, but I wasn't a DevOps engineer. So, I made sure that as I worked through anything I was doing, I added it to this enormous glossary spreadsheet that I now maintain and have available for our company that includes basically any term that you might come across in working at Amazio that you'd have to define, just about anything. And that's been really helpful to me and to others in getting on boarded and just learning all of the language of DevOps and what we do here. And it leaves a lot less sort of lower-level definitions for engineers to have to explain when they're explaining how something works. And that sort of goes into my next point of doing your homework on the software before meeting with the engineers, familiarizing yourself with, you know, what you're working with before you go in and ask more specific questions. Because you're also going to need the 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. 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 managing and writing documentation is part or all of their duties. If that's not feasible, take a look at your team and their strengths, their available time and willingness to take on the task. This person is responsible for not just writing the documentation, but managing it and ensuring that changes are made in a timely manner. So, this includes receiving and integrating feedback. Most teams will find it easier to use whatever ticket system they use for code to track needed changes or additions to documentation as well. So, determine a process for updating documentation. Will it be revised on every minor release or just ad hoc when there's something to update? Will you check on certain parts every so often to see if anything needs to be updated? How will you organize tickets and issues? So, I have an overarching documentation epic in JIRA so that I can see all of the related tickets because they're not always assigned to me. You know, sometimes I need information so I assign it to somebody else. And this lets me keep an eye on all things documentation going on. How to get buy-in from stakeholders. And this is one of the most difficult things and it can really depend on your situation. But there are some basic advice that you can start with. So, some clients or stakeholders push back on documentation as something extra. Anything that takes time costs money. And documentation is often seen as something that can be cut from a project to save costs or something that can be done later. So, how do we convince them otherwise? Good documentation brings in users or customers. Documentation not only helps users to interact with your project but can serve as a marketing tool. Bad documentation is just the opposite. Bad or missing documentation turns users and customers away. So, without documentation or with frustrating documentation, you risk losing or turning off potential users or customers. Good documentation shows that you're thoughtful, that you've worked through these issues and provided these solutions to your customers, and that you care. Keeping everyone informed avoids a crisis later. So, 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. So, documenting what changed when is a key part of troubleshooting and can cut down on time and costs. When developing a product and documentation for the client, keep them involved. Make 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 handover is done, the clients have already reviewed all of this documentation. Hopefully, they've asked any questions that have arisen and now they're ready to take the helm. So now they'll be less likely to break things or need emergency support. Let's go over some ways to get started writing your documentation. First, we want to define your audience. These are just some common examples. Your audiences may obviously 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 your system but not coding and maintaining it. Answer the basic questions. Make sure that as you flesh out your documentation, you're answering these basic questions. You use these to write just about anything and documentation is no excuse. Who is this system or product for? Why are certain things the way they are? If you've coded something in a way that might seem a little bit out of the norm, document that. Explain why. Future you and future developers aren't going to know why. When would I use this? Provide use cases and examples. What does the product or system do? It's amazing how many documentation pages or home pages of various pieces of software I get to, and nothing actually tells me what the product does. How does it work? And where can the user find the info that they need? So what makes bad documentation? We've talked about some things to make good documentation. Here are some common pitfalls. Incomplete, missing steps or information makes your documentation useless. You might as well have nothing if you're going to have incomplete documentation. Out of date, if your documentation doesn't match the latest version of your code, it won't help users. I'm sure we have all been in the middle of following a step-by-step process and have it completely fail only to realize that it's for a different version of the product than we have and we're completely lost because we have no idea what to do because there is no more documentation. Inaccessible, if your users can't find your documentation, they can't use it. And not inclusive. Ensure your language is welcoming to all. I've actually done an entire talk on writing inclusive documentation. But some of the key points here are making sure that you're not using too much jargon, that you're considering people who are not native English speakers, that you're not berating the user, which I see more often than you would think. Don't make fun of your user. It's not a good way to get clients or customers. So be welcoming. You want people to use your product. Some other common pitfalls include making your documentation hard to read. So making attractive, stylish web pages isn't just for aesthetics. People are more likely to read something with nice white space that doesn't have walls of text that's attractive. Make your documentation available as content that's updateable. Don't release it as a PDF, for example. Once they're out of date, they're gone and they can't be taken back. They've been downloaded. Do you have no control over them? So those are a couple of things to avoid as well. So here are a few steps to improving your documentation right now. Get out your red pen. Go through and note anything that is incorrect or out of date. Slim, accurate documentation is better than having lots of inaccurate documentation. You can be brutal here. You're going to build it back up. Define your audiences. We talked earlier and gave a few example audiences. 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 are going to need your basic getting started info. Make sure that you have that complete before moving on. You know, tell people how to get your stuff installed. That's the first thing they need to do. So tell them how to do it. Plan out a taxonomy. When you're writing new pages for your documentation, where will they go? Take a look at the information you need to break down. An outline is really helpful here. And plan out your information architecture so that for each piece of content, you can answer, where does this go? So this is something that we've been working on at Amaziego. We recently released our new updated documentation. And while we didn't make huge changes, even just some small changes like moving our documentation into a basics and advanced category seemed like it made just a huge difference. So think about things like that. You know, when we sat down and thought about our audiences and that's something that's still a little bit in progress. But, you know, think about the way that you can divide up your content so that you don't just have huge walls of pages, huge walls of menus, huge walls of text. And we mentioned this earlier. Take a look at the design. People naturally prefer to read things that are pleasant to the eye. Make sure that you don't have long paragraphs where a list will do. Use images where they're indicated. Make use of white space. Use semantic markup. And choose styling that is modern and attractive. And of course, this should be accessible as everything on the web should be. Take it slow. There are no shortcuts to good documentation. Sure, you can generate documentation from your code comments. And that has a place. But that's no substitute for actual written instruction from a human being. It's just a part of your documentation ecosystem. So this is a pretty short talk because I originally wrote it to fit into a 25-minute slot. And I thought that I would rather just open up for more questions instead of trying to beef this out. So a couple of resources for documentation. Write the Docs is an amazing community. They have conferences. They have a Slack channel. They have a website. And when I was doing research, I also found these technical writing courses from Google that seem pretty in-depth and pretty good. And how do I get better at writing is something that I get asked a lot. And this seemed like a good resource to point people to. So if there are any questions, let me take a look at the chat. Oh, Benji commented, I dislike video documentation. It's so hard to update. It can be, yes. I have been making some video content for us. And it can be very hard to update. I have tried to make it in a way that is updatable for me. But we also have thought of our videos as very supplementary to our documentation. So if you're going to make something like videos, make sure that, one, that you're aware of them and where they are in the scope of your documentation, like when to get rid of them or when to retire them. And also, we don't have any videos that are crucial to our documentation. They're all just supplemental. They're all just demos showing things off, explaining things in another way in case people learn better of that way. I don't like video documentation, but I know that there are a lot of people out there that do. So we have been producing some of it to just supplement our existing documentation and see if that helps people. Let's see questions. With four types of documentation. One, it can be a massive task to keep it all updated. And two, there can be a lot of repetition. Any recommended tools or strategies. So it can be a lot of repetition. It can be a huge task to keep it updated. So, and one of the things that makes it easiest for me is that it's the primary focus of my job. And I get a lot of support in it. There are other people who help out with it. And some of it doesn't change that much. So think about like the readme's, those don't change a lot. The code comments are primarily the domain of the engineers. Let's see, let's go back to that slide. Here we go. So yeah, readme files don't change a lot. Inline code comments are largely the domain of the engineers. Release notes are also the engineers and the folks arranging the releases. So the external doc pages are the thing that changes the most for me. So that's sort of, that's my most day to day work. And then I just keep on top of, when we ever we do a release, I make sure that I keep on top of reading all of those and that I'm aware of everything that's in it. If anyone makes a change to a readme file or if I'm aware of anything that needs to go in a readme file, I take a look at that. I make sure that I'm watching any repos that I need to be watching, that I'm responsible for, and that all of that info is coming to me. And I mean, inline code comments isn't really my domain. So it seems like a lot, but it's not the same thing every day. And where do you store and maintain the list of terminology in your company? Oh, I just have a Google spreadsheet and I just started writing down lists and I actually keep it pinned all the time and see how many terms are on it now. It has 267 terms going from ABI for application binary interface all the way down to YAML. So that's my giant lossery that I keep. And I periodically remind the company that I have this. And every time I find a new term, I just throw it in there, even if I don't have the definition right away, so that I remember to go and define it or find the definition later. I always say that writing documentation is easy, assuming that the audience is your current self. Maybe add an item to the list of ways to improve. Oh yeah, getting feedback, that is a great one. And that reminds me, so I found a really great way to improve our documentation recently. So we just moved our documentation to Gitbook. And Gitbook has this really great, they have like integrated search and analytics. So you can get these great lists of terms that people have searched for in your documentation. So I'm just taking these lists. I just saw it for the first time yesterday, the day before. And so now my plan is to take these lists weekly and look at the terms and see what terms people are searching for and do we have those terms in our documentation? Like are we addressing those terms? And assuming it's appropriate to address those terms and they weren't something wacky, let's make sure that we're addressing them. If it's something that people were looking for, like the top search was like SSH. And I thought, hmm, I don't think we have a ton of stuff about our product and SSH. And it was the top search. So we better look into, you know, figure out what people are probably wanting to do exactly and document that. So that is like this built in what people are looking for function in our documentation, like just for me. And it is going to be so helpful. So I hope, let me know if you need, if those answers were helpful. And if you have any more questions, we have time. Any more questions? If not, I can give you a little chunk of your Saturday back and you can go get some more coffee. What is your workflow for external documentation pages? Okay, so right now we, like I said, we're using Git Book. And Git Book allows for editing either from the Git Book WYSIWYG or from GitHub and it'll sync either way. So if our GitHub workflow remains unchanged, we, you know, check it out, edit the markdown, push it up, pull requests, et cetera. So that's the same as it's always been. But we are really enjoying the WYSIWYG in Git Book that allows you to edit in there and then you can essentially stage your content and have others take a look at it and review it. And then you can merge it and it goes back into GitHub, which is fantastic. So right now, the only people who are editing in the WYSIWYG are myself and my direct manager. So if we edit anything bigger than, you know, a typo or a few words right now, our process is just to have the other review it. And it's really nice to just not that I don't like having to put in a pull request and have people review it. But if I just have to change a few words or something, it's lovely to just have a WYSIWYG and just fire that off. And because we just started out this new system, we're not sure if we're going to have any more robust review systems or if there are more people who might be editing from the WYSIWYG side or if we'll put any more controls in there. But right now, it's just the trio of us editing from that side. So we're just doing a quick manual review before we merge that. But it is really cool that they have a staging and then merge functionality. I really, really appreciate that. It's really handy. Not sponsored by Git Book. I just have been working with this software all year and I really enjoy it. Would it be fun to compile a list of documentation fails or just depressing? I think it would be really depressing. And I think it is too early in the day even though I'm on the East Coast to start drinking. So I don't think we should do that. Anything else? Any other comments, questions? I'm always around on Slack or Twitter. If you have any questions, you want to talk documentation. You want to convince me to contribute to documentation on your Drupal.org module. I'm around. I love documentation. It's my favorite. All right. Well, thank you all for coming, everyone. Have a great rest of your day and a great rest of your bed camp.