 Hello. This is creating a culture of documentation. I'm Alana Burke. This is the talk we're in. And these are the ways that you can contact me. You can find me on Twitter, Mastodon, and on the CNCF Slack. I am the community manager, developer relations, and documentation writer at amaze.io. So today we're going to talk about a handful of things all revolving around documentation. We're going to find out what is documentation? Why is it important? What makes good documentation and what makes bad documentation? We'll go over what leads to documentation failure, and then we'll talk about some of the consequences of bad documentation. Then we'll talk about ways that you can change your culture and a few ideas of what to do if none of that works. So first, what is documentation? And what does it do? There are a million answers to this question, and none of them are wrong. But some of the main things that documentation does is it guides our users. Often our documentation is a series of numbered steps that users go through. So we give them these guides on how to use our products. It also explains the code. So there's a lot of things that you can try to understand by looking at the comments and the source code. But sometimes you need to just break out into pros and explain exactly what your code does. Documentation can also show thought leadership. I think more people are realizing this, but documentation can also be a way of marketing yourselves, showing, hey, we know how to do this stuff. We know how to build this stuff. This is what we're doing here. Documentation also establishes processes, whether you're talking about tech documentation, internal documentation, financial documentation, it establishes all of the steps that you are supposed to go through for a given event. And documentation can also onboard new customers. So when you get a new customer using your product and you need to guide them and show them how to get it installed, how to start working with it, that's one of the many things documentation can do. So why is good documentation so important? Well, it can make for better onboarding both of customers and new employees. If your customers get frustrated and they can't figure out what they're supposed to do, they're not going to come back to you. Good documentation also gives us faster troubleshooting, having to remember fewer things because we have them all written down and documented and we know why these things happen. And because of those past few things, it retains users and customers. So when customers can fix their problems easily or they have fewer problems, they're going to be happier and they're going to stay. Good documentation also improves productivity, making sure that your, you know, say your support team doesn't have to sit around and try and Google things all day because we've got it all documented. And every time they need to fix something, they know where to look. So in doing that, we also save time and we can avoid miscommunications. When all of your knowledge is stored in people's heads, things can start to diverge and information can change. So when everybody is referencing the same document, you can avoid any miscommunications. And then finally, one of the reasons that the documentation is important is that it helps you manage changes. So think of things like comprehensive release notes pointing out in the documentation that all of these things have changed. So why are good docs important? This is a study with Cornell University and they found out that 61% of professionals in distributed teams say it can be hard to figure out what their colleagues are working on. 44% said that siloed digital media tools made it hard to spot if work was being duplicated. And 62% of people reported missing opportunities to collaborate with their co-workers and achieve better results. So when you have bad documentation, it's hard to know what's going on in your company, what other people are doing. Are you guys both doing the same thing as one of you doing it wrong? We won't know because it hasn't been documented. And one of the reasons that we need to document everything is that humans are terrible at data store it. So we talked a little bit about what makes documentation so important. So let's go over some examples of what makes documentation good. So good documentation is easy to understand. Doesn't use a lot of jargon. Doesn't use overly complicated terms of phrase. It's straightforward. Good documentation gets to the point. It doesn't tell you a whole story before trying to tell you what you need to do and what you're actually looking for. Good documentation also has good visuals. People inherently look at things that are nice to look at, that are pleasing to look at. We want to look at them more and we want to look at them longer. So if you have difficult to read documentation, people aren't going to be inclined to spend as much time looking at it as they will if you have very nicely designed, nicely laid out documentation with interesting things to look at. Good documentation has also been vetted for accuracy. There's nothing worse really than inaccurate documentation. Good documentation also includes the author and date. So if there are any accuracy problems, we know when they were introduced and how that happened. We also know how old this documentation is if we run into an error. And finally another thing that makes good documentation is addressing the right audience. If you're targeting the end user, make sure that that's the person who's getting this information. If you're targeting administrators, make sure you tell them which information they need to know. So we're going to go through some examples that I have found in various places on the Internet of good documentation. So this is some Kubernetes documentation that may look familiar to some of you and I just wanted to zoom out and show that it has a lot of different things visually going on to keep you interested. So it's got headings. It has callouts, which use color. We've got sort of red going on here, if you can see that. We've got a table. The table has highlighting so that you don't get lost looking at all the different rows. We've got some code. We have bullet points. We have another callout. So it's just really showing that there's a lot more to documentation than big walls of text. Here is a more zoomed in example of a Kubernetes documentation page and I've shown that they have some text that they've underlined and I highlighted it and you get a nice little tool tip that defines something without even having to leave the page. We also have at the beginning of that sentence, we've got something highlighted in code and it links out to presumably what we're talking about here. And again, we have callouts and buttons. It's just a nice page to look at. Here we've got one of my favorite things, which is making sure that if you have a code block, you're telling people where this code goes. So in this case, we have an application deployment.yaml file and on this example, we have a place where people can give feedback to tell them whether the documentation was good. And we have not only the author and date, but a link to the get commit that updated this documentation. Now this one doesn't score very high on the visual points. This is yet another deeply dug in Kubernetes page that gets automatically generated. But what I really did like was that for all of the things that they're defining here, we have examples. This is from another tool, Twilio. And this is a really great example of making sure that you're addressing the right audience. So right on their main documentation page, they ask you, are you a developer? Are you administrator? Or are you an end user? So next up, what makes bad documentation? Bad documentation is fragmented across platforms. If you have documentation that's in three different places, people aren't going to be able to find it. They won't find all of the things they need. Bad documentation is incomplete. If you've only shown people how to use a part of your project, how is that helpful? How does that get them anywhere if they can only get so far? Similarly, bad documentation is out of date. If you've updated your product, if you haven't updated your documentation, what was the point in updating the product? Bad documentation also makes assumptions. If you make assumptions about what your users know or what they're able to do, you may have people having lots of difficulty with your instructions and your documentation. If you are asking someone to do something, tell them what they need to do or state at the beginning of the documentation what your expectations are. Bad documentation uses jargon, especially in the tech field. We work with people from around the world who speak many languages and many people don't speak English as their first language. Avoid using lots of jargon and slang and things like metaphors that might not make sense. Finally, bad docs are tailored to the wrong audience. We had an example. There were developers, administrators, and end users. All of these people are going to use this product differently. They're all going to need different documentation. Here are some examples of bad documentation. This is from the Drupal project. The maintainer of this module is a friend of mine, so I'm allowed to poke out the issues here. This particular example is the media module, which is a very essential module in Drupal. Somehow one of the main pieces of documentation about this module has not been updated since November of 2020. Here we had some screenshots showing how to do things, and I did not make these screenshots any smaller or blurrier. They were small and blurry. There was no way to figure out what exactly you were doing, and there was no way to increase the size of these screenshots. So Drupal is now on Drupal 10, and yet this main guide to this very core module is only about Drupal 8 and still supports Drupal 7. It seems like we're at odds here with trying to push the latest and greatest, but somehow one of our latest and greatest modules isn't so late and great. And then this is the Ubuntu documentation. I actually saw someone tweeting about how bad their documentation was, so I was like, oh, I need to go check it, look at that. This is the main help.ubuntu.com page, and each one of these things that I've put a green square around goes somewhere different, which is pretty bad. Their documentation is really, really fragmented. So what leads to all these documentation failures? How do we get here? Docs are often everybody's problem and nobody's job. People will say that they have no time. They often have no incentive. If you're only expected to do ABC deliverables, why would you also add extra work for yourself? A lot of people have no experience. They just don't have experience with writing. They don't have experience writing technical documentation, or they just don't feel like they're good enough writers. Sometimes there's often red tape. If your documentation doesn't get prioritized as a deliverable, but say a client is demanding the documentation without giving you extra time, things can start to turn into problems, and everybody gets caught up in it. Another thing that leads to documentation failures is information hoarding. When you have somebody who's been there for 50 years, and they know how to do all the things, and they don't want to tell anybody else how to do all the things because they don't ever want to lose their job. And then finally, documentation can be hard to keep up to date. It's hard to go through all of your documentation frequently and make sure that it's all updated and that nothing is inaccurate. Sometimes that requires talking to lots of different people, checking lots of different things. And again, if this isn't a priority to somebody who's paying for it, how does it get done? And then see, these are some of the common excuses that lead to documentation failure. The code is self-documenting. We've all heard and said that before. It's too hard to keep it up to date, and it adds too much time to my development. So what are the consequences of bad documentation? This is a case study from Google from a little while ago. 48% of Google engineers cited bad documentation as their number one productivity issue. 50% of SRE issues cited problems with documentation. And this is where I got that quote, docs were considered everybody's problem and nobody's job. So what did they do? Sorry, trying to... So what worked for them was changing the status quo. They made documentation radically simpler for their engineers. They made a system that they called G3 docs, and it did the following for them. It removed decisions. It presented one way to document things, and that was the only way there was, and there wasn't anything to be done about it. They also hosted their docs in the source code in Markdown, so that their engineers could stay in their IDEs and work on the documentation at the same time. Their documentation system automatically rendered out that Markdown into nice HTML pages. They also formed alliances with influential engineers to introduce... Oh, is what? Oh, no, I'm good. It's the same slide. Okay. So they formed alliances with influential engineers to introduce the tooling, and they partnered with specific teams to build strategic integrations so that everybody was on the same page with the documentation. They also released and iterated it in the open so everybody knew it was going on, but they never forced teams into it. They had teams lead by example. That's why they reached out to some of their most influential employees and got everybody on board. Here's another example of consequences of bad docs with some numbers. So I found an article that had these numbers in it. If IT folks spend about 20% of their time just looking for information, here's how much gets wasted. So say the average salary, we're not paying these people very much, is $60,000 a year, which makes their hourly rate about $43 an hour. If we say they wasted 20% of their time due to documentation, that cost is about $13,760 a year per employee. And so the opportunity cost, which is the amount that they would have made if they hadn't also been wasting time, is about $34,400 per employee. So for a 10 employee company, we're looking at quite a lot of money here, and that wasn't a very big example. And these numbers were put forth by a company that was offering documentation, but I thought it was interesting to break it down this way and see not just could you gain money, but how much money is actually lost by bad documentation. And I believe it's very strongly that bad docs are worse than no docs. I would rather Google and Google and never find an answer than find an answer, try to follow it and figure out that it's wrong. So how do we change our culture? And some people try to argue this, but culture is not immutable. We can change it. So we're going to go through each of these things. You need to start from the top, choose someone to drive it, make it easy, start with standardization, and empower your contributors. So how do we start from the top? We established that clear, concise writing is the expectation from everyone. And to do this, ensure that your higher ups and your stakeholders lead by example with quality writing. Make sure the people that everyone looks up to, that the people who are being followed are the people who are giving the right examples, that they're proof reading their emails, that the documents that they produce are high quality. Choose someone to drive it, make someone responsible for managing documentation. Even if like me, that isn't that person's entire job, make it someone's official responsibility. And this person also generally creates templates, trainings, and any other support that's needed to create the documentation. Make it easy. Choose tools that integrate into existing workflows like Google did. Let developers stay on their editor. I know that every time I have to switch a window, I get that much more distracted. So the more you can let people stay in the flow that they're in, the more work they're going to be able to do. And use version control like Git so that everyone can contribute easily. And ensure that everyone has access. Don't make your documentation platform something that everyone has to request access. Grant everyone access so the expectation is that they're contributing. Here's another case study from Twitter. So back in 2014, Twitter had three technical writers. What they did to actually get their documentation off the ground was to encourage documentation via their special doc days, which were essentially sort of hack days where everybody just got on board and wrote documentation. They built a new docs as code stack. There's what's called Doc Bird. And they created nice documentation templates for everybody to follow. So the doc days were what really helped. They just had the technical writers give trainings, help edit, and review all the final documentation. And then the bigger purpose of this was to evangelize and normalize documentation as a practice. So it built a community around it and around the expectations that they had on documentation. So make sure that you start with standardizing everything. You want to always establish a tool set. Create a style guide. Have an approval process. How do documentation get from point A to point B? Create templates to make generating documentation easier. Use spell checkers and linters so the people who are very worried that they're not good writers can relax a little more and establish a maintenance schedule. When is the documentation being reviewed and who is responsible for doing it? These are some examples of documentation tools that I really love and that are very popular. Markdown is obviously one of the most popular languages for writing documentation. The read the docs platform is really great. They allow for the following two documentation systems. Make docs, which is a documentation generator that's fast and very simple. And then Sphinx is a more powerful documentation generator that's really good for technical documentation. Gitbook is a nice platform if you want something that's not open source and is a little more shiny. And then of course the one that we all dread is Confluence, which I feel like everyone uses for their internal documentation. It never goes away, but it is actually a pretty good system. There's one more case study. This one is from an anonymous Fortune 500 company. They got documentation writers on board contractors who helped this client reduce their content overload. They had way too much content and increased their content reuse by 20% year over year. It helped reduce their support calls by 35%. And then the guidelines that were designed for this client were implemented so that they would be the standard for all future releases of documentation. Empowering your contributors. Use a system that allows for contribution from everyone. One of the reasons things like make docs are so popular is that they allow for everyone to contribute. And these days you don't even need to be able to edit Markdown in an editor. You can use GitHub or GitLab. Their inline editors are absolutely totally serviceful for things like editing documentation. Create a positive feedback loop when people who have historically been resistant to writing documentation decide to start writing it. Make sure that you thank them, that you tell them they did a great job so that they'll want to do it again. Give trainings on how to write docs. If your team feels like they don't know how to write, they're not good technical writers, give them some training. Give them the tools that they need. And then all of this will allow everyone to have a sense of ownership over the docs. You know, people don't always see the functions that you write and the pieces of code that you put together. But you can have some pride of ownership of knowing that people are reading your documentation. So what if it doesn't work? There's a few things we can do. We can go the slightly more forceful way and just don't accept merge requests that don't include needed documentation updates. Make an expectation that the documentation is just as important as the code. You can also make doc writing an official part of everyone's job description. If everyone who has writing code in their job description also has writing documentation, again, we're establishing that expectation. And then finally, develop an intrinsic value. Make everyone feel the need to update the documentation, to write the documentation, to get it out there. Get people to understand that this is the way that people use your product and this is the way that they're going to understand it. And if you want people to embrace and use your product, you'll have to write the documentation. So that's all I have. Here's my contact information again. I love talking about documentation. I have, there's a slide after this where I have all of the talks that I've given on documentation and these slides are already up in the sketch app. These, again, if you grab the slides, these are the references. And then these are some of the other talks that I've done. I have videos and slides for these if you'd like to check them out. So thank you.