 All right. I'm going to get started. So this is creating a culture of documentation. I am Alana Burke. My pronouns are she and her. I am the community manager. I do developer relations and documentation at Amazio. You may have seen our booth upstairs. You can find me on Drupal.org and Twitter at aburk626. You can find me on Mastodon. And you can also find me on the Drupal Slack at Alana Burke. So we're going to talk about a handful of things today. We're going to talk about what is documentation? Why is it important? What makes for good docs? What makes bad docs? What leads to documentation failure? What are the consequences of bad docs? How to change your culture? And what to do if it doesn't work? So what is documentation? And what does it do? So documentation guides your users. Documentation also explains your code. Documentation can help you to show thought leadership. It establishes processes. And it can onboard new customers. Obviously, these are just a few of the many, many things that documentation can do. So why is good documentation so important? It allows for better onboarding, both of customers and of new employees. It allows for faster troubleshooting, helps you to retain users and customers, improves productivity, saves time, avoids miscommunication, and helps you to manage changes. So why are good docs so important? 61% of professionals in distributed teams say it can be hard to figure out what their colleagues are working on. 44% say that siloed digital tools make it hard to spot if work is being duplicated. And 62% report missing opportunities to collaborate and achieve better results. This is all from a study with Cornell University. Humans are terrible at data storage. This is one of the reasons that we need to document things. So what makes for good documentation? Well-crafted documentation is easy to understand. It gets right to the point. It informs your users and enables users to successfully accomplish a task. It has good visuals. It's pleasing to look at. It makes you want to continue reading it. It also is vetted for accuracy. And it includes an authoring date. This allows you to know when it was last updated, whether it's out of date, and who to go to to get it updated. It also addresses the right audience. For example, someone who administers a site, someone who's developing a site, and someone who's designing a site might all have different needs and different documentation, and they're not all going to want to read the same thing. So these are some examples that I've put together of what makes for good documentation. This is from the Kubernetes documentation. This looks a little blurry up here, but you can see up at the top, we've got a call-out giving you lots of information. We've got a table. We have some different code. We have a highlighted code. We've got, basically, there's just a whole lot of different ways that they're displaying information. It makes it interesting to the eye. It makes it pleasing to read, and they're presenting a lot of information. Here's another one from the Kubernetes documentation. I really like that they had these little tooltips for quick definitions so that you don't have to go to another page just to get a definition on an acronym here. Here we've got some nice documentation showing how they're using this code. We've got examples. Again, it's easy to read. It's displayed plainly, but all of the information that you need is there. I also like documentation that has good outlines. We've got the outline over here showing what the table of contents is, and then we have what's on this page on the other side. We also have some examples of showing the date and author at the bottom. Is that? Sorry, skipped to go back. There we go. This one's got the date and the author at the bottom, and also a nice little thing that you can tell whether or not this page was helpful and if you got what you needed out of it. This one isn't as pretty, but I really liked the way that they did this. This is some of Kubernetes automated API documentation, but I really enjoyed that they had all of the information about how to use it, all of the flags, the usage, but they also had these examples over here, and I thought that was a really nice way to do it. Here we've got some documentation from Twilio, and this is a good example of how to address different audiences. So they've got their development documentation, their administrator guide, and their end user guides. So now let's talk a little bit about what makes for bad documentation. We've seen some good docs, so what makes for bad docs? Bad docs are fragmented across platforms, making it hard to find what's where. Bad docs are incomplete, they're out of date. Bad documentation makes assumptions about what the user knows is able to do or has already done. Bad documentation also uses jargon. We have to remember a lot if you're a native English speaker that many other people especially in the tech world are not English speakers and won't understand various jargon and slang. Bad documentation is also not tailored to the right audience. So here we have some examples. This is from the media module, and I had permission to criticize this. So here we have, it is telling us when it was last updated, but unfortunately it was last updated in 2020, which for a core module is not really great. And here the problem that I had with these screenshots is that they were so small, so hard to read. There was no way to actually increase the size on the page. If you clicked on them, they didn't get any bigger. They were so blurry. So, and there was no alternative text or caption to tell you what was actually going on in these screenshots, which were pretty important since they were telling you how to make a media type. And here we've got documentation and this is the main media module documentation page, and it's telling us that this guide is about the D8 media module, but we've also got this banner telling us that we should be on DRIPLE 10. So, should we be using the DRIPLE 8 media module? Should we be using a DRIPLE 10? What's going on here? And this is some Ubuntu documentation. I actually saw someone complaining about this on Twitter, so I had to go and look. Ubuntu's documentation is so fragmented. It is unbelievable. All of these links that I've highlighted go somewhere else. They all go to various different sites for documentation. It's kind of absurd. So, what leads to all of this kind of documentation failure? Docs are often everybody's problem and nobody's job. You will hear that there is no time. There's often no incentive. Most of the incentive that developers and engineers have is to get the project done, to get the code done to deliver what's going to be functional, not what's going to be read or support the project. A lot of people who have the knowledge to provide the documentation have no actual experience writing documentation or technical writing at all. There can also be red tape. If you are booked out at 40 hours a week of coding, how are you going to get documentation done if no one is supporting you in that? Information hoarding can also be a problem, especially when it comes to internal documentation, getting people to get the information out of their head and somewhere else so that everyone can share it. And documentation can be hard to keep up to date. You have to establish a schedule, decide how you're going to maintain it, when you're going to maintain it, and who's going to maintain it. So, here are some of the excuses we hear a lot that lead to documentation failure. Who's heard this one before? The code is self-documenting. Who's said that before? It's too hard to keep it up to date. And it adds too much time to my development. What are the consequences of bad documentation? This is an older case study from Google, in which 48% of Google engineers cited bad docs as their number one productivity issue. More than 50% of their SRE issues cited problems with documentation. And this is where I got the phrase, docs were considered everybody's problem, but nobody's job. So, what did they do? What worked for them to start changing the status quo? They made documentation radically simpler for their engineers. This is something they developed called G3 docs. And it did the following. It removed decisions. They presented one way to document things. That was it. The only way they could do it. They also hosted the docs next to code so that their developers could stay in their editor, stay in their IDE. They used Markdown, so no one had to switch what they were doing, go to another program. They could stay in their workflow and create the documentation. This system also allowed documentation to get automatically rendered into nice HTML pages when it was committed. They also formed alliances with influential engineers throughout the company to introduce the new tooling. They partnered with specific teams to build strategic integrations. They released and iterated on this project in the open and they never forced teams into this new workflow but led by example. So, some consequences of bad documentation. Having to redo work because the requirements were unclear, this obviously wastes time and money. Missing info on areas of your code base and making your docs hard to find and wasting time. So, this was an interesting set of facts that I found. This was just in an article but it said that if IT folks spent around 20% of their time just looking for information, if we say that that average salary is about $60,000 a year and their average hourly labor rate was $43 an hour, time wasted due to bad documentation was 20%. The annual cost of time waste per employee was, and this is in US dollars, $13,760 per employee. Making the annual opportunity cost of time waste $34,400 per employee or more than half their salary. So, the opportunity cost is the amount of production that each employee could have produced had they not been wasting time looking for things. That's a lot of money. For a 10 employee company, we're looking at about half a million dollars in waste every year. So, if good documentation could cut that in half, I think most people would be pretty pleased with that. And this is one I believe pretty strongly that bad docs are worse than no docs. You know, if you go out looking for something and you can't find any documentation on it, you're not gonna do anything harmful, nothing bad is going to happen, you're just going to have to figure it out on your own. If you find bad documentation, it's gonna screw you up, you're gonna wind up down the wrong path and you're gonna be really frustrated. So, how do we fix this? How do we change our culture? I really like this quote, culture is not immutable. So, we're gonna go through each of these, but these are the things that we're gonna try to do to change our culture. Start from the top. Choose someone to drive it, make it easy. Start with standardization and empower your contributors. So, start from the top. Establish that clear, concise writing is the expectation from everyone. Higher ups and stakeholders need to lead by example by quality writing. If your C-suite employees are sending out emails that are full of mistakes and typos, they're difficult to read, then they're not going to be setting an expectation that good quality writing is what everybody needs to be producing. So, we need to make sure that everybody from the top down is on board with this. Choose someone to drive it. Make someone responsible for managing documentation. This person would also create templates, trainings, and any other support needed to create docs. At MSIO, that person is me. It doesn't have to be someone who does it full time, although that's very often needed and very often preferable. I wear a couple of hats, so while this is my responsibility, it's not my only responsibility. And make it easy. Choose tools that integrate into existing workflows. Let devs stay in their editor. Using Git or Bitbucket or GitLab, whatever you want to use makes this a lot easier and there's a lot of great tools that integrate with Git, GitHub, GitLab to create your documentation. And ensure that everyone has access from the get-go. Don't make people have to request access to contribute documentation. That just creates a barrier to entry. Make sure that everyone has access immediately. So this is an older case study from Twitter, although any case study from Twitter that's more than a year old would probably be wildly out of date, but I thought this was still interesting. So in 2014, Twitter only had three technical documentation writers. So they started to encourage documentation via education and these days that they would set aside called doc days. They also built a new docs as code stack that they called DocBird, and they created a lot of documentation templates. So the doc days were these single day hackathons where developers would update the docs. Technical writers would give training on that day, and then they would help to edit the final docs. So the bigger purpose of these days was to evangelize and normalize documentation writing as a practice. And it built community and set a common set of expectations about documentation. And then to make their documentation easier and more standardized, they launched this new DocBird docs as code stack, which was basically a customized wrapper around Sphinx, which if you've ever used, read the docs, Sphinx is one of the options you can use there. It was actually very similar to what Google had with G3 docs, building your documentation from source automatically. It also, for them, removed all of the questions of where are the docs because they put them all in one central place. Start with standardization. Establish a tool set. Create templates. Create a style guide. So ever since I started at Amazio, I have kept this Google doc that is our technical manual of style where I put everything that I come across that needs to be documented. It also has a list of like, these are all the terms that we use commonly that are camel cased. These are all the ones with weird spellings we might forget. These are all the ones that aren't camel cased. This is some weird grammatical thing I ran into and I figured I would document so that we don't have to look it up again. Use spell checkers and linters. Have an approval process. And establish a maintenance schedule. There are lots of various documentation tools out there. These are some popular ones that I like. Obviously, Markdown is a great language for writing documentation. It's pretty intuitive. Whether you're a developer or an engineer or not, you can use it. Gitbook is a pretty good tool. We used it for a while and then it wasn't working for our needs but I still really enjoyed it. Read the docs is very popular. Confluence is where a lot of people wind up using their internal docs. I don't think anyone really loves Confluence but it is very robust. There's also MicDocs which we now use for our documentation. And as I mentioned before, there is Spinks which is the documentation generator. So this is a case study from a Fortune 500 company. This was from a website that did, it was like a company that did documentation for people so this was their case study on this. And they helped their client reduce content overload and increased content reuse by 20% year over year. They also helped to reduce their support calls by 35%. And then the guidelines that they designed for their client were also implemented as their standards for all of their future documentation releases. And finally, you want to empower your contributors. Use a system that allows for contribution from everyone. One of the reasons that I love that we host our documentation in GitHub is that anyone who's intimidated by using an editor or an IDE or markdown can just use the GitHub WYSIWYG and edit the documentation. It's not a big deal. Make sure that you give trainings on how to write docs. Have documentation for your documentation. Create a positive feedback loop. If you feel like you are constantly trying to bug someone or a group of people to get documentation done when they do it, thank them for it. Congratulate them. Tell them you're really happy that they did it. Make them want to do it again. And that sort of ties into allowing everyone to have a sense of ownership over the docs. If people feel like they have responsibility, if it reflects on them, and they're more likely to want to do it and to do a good job of it. So what if it doesn't work? There's a lot of things that you can try to do if it doesn't work, so these are just a few examples. One really straightforward one is just don't accept merge or pull requests that don't include the needed documentation updates. Reject them until the documentation is there. My coworkers are making faces because if I did that, I don't know what would happen. Make doc writing an official part of everyone's job description. Make it so that engineers are required to write the documentation along with their code. And as I mentioned before, develop an intrinsic value. Make everyone feel responsible for the documentation. If an engineer is responsible for this part of the project and this part of the code, make them feel like they're also responsible for this part of the documentation. If they're really proud of this feature, then they should want it to be documented because if it has crappy documentation, then people won't be able to use their great feature. And that's it. We have a few more minutes, so I'm happy to take any questions. I'll also put my contact information back up here. If you wanna reach out on Twitter or whatever, I am here. Yeah, go ahead. Okay, so for the recording, the question is, budgets can be tight, and is there a set amount of hours or percentage of development time that should be set aside for documentation? I think that's gonna depend a lot on what you're documenting and the degree of difficulty of the documentation. Some things are gonna be a lot more straightforward to document than others. It's going to depend on who's doing the documentation and their level of expertise and what they have to do. So I think that's the kind of thing you need to sit down on. When you are first planning for the project, sitting down with the project managers and the people who are going to be doing the work and figuring out what has to happen. For example, when I came on board, I had a huge documentation project to do, but I didn't know the technology, so I had to watch recordings of presentations and I had to sit down with engineers and I had to do a lot of work to actually get the information. So that was obviously a lot more time consuming than if one of the engineers was doing the documentation themselves because they had the information, but I had the technical writing skills. So I don't think that there is any one answer as to what percentage it should be, but it's something that you wanna make sure that you're figuring out at the very beginning and not trying to shoehorn in at the end or after you've already figured out what your budget is and what your time is. All right, well, thank you very much. I will make sure I get these slides up. I've also got all the references I used for this talk and links to other talks that I've given on documentation that you might find helpful. So thank you guys.