 Well, thanks everybody for showing up. This is the good the bad the documentation and yes I did think that title was funny when I was writing it and no I didn't think about how long it would be on my slide presenting it I Am super thrilled to be presenting to you guys about documentation. This is a really big hobby of mine. So If you've had the pleasure of talking to me at this conference, it's definitely come up once twice Maybe three times This session is actually targeted towards anybody who writes documentation. So we're gonna look at your documentation Not just inside your code, but outside of it as well My name is Jennifer dust and I am a full-stack developer with Atten design group My background is based in higher education and working with non-for-profit organizations such as girls who code I've had the privilege to work as a web developer and teach at the collegiate level For several years and having completed two master degrees I've certainly learned a lot of ways of how not to write which is great I have been with Atten for two years and Atten has been around for 22 years providing strategy design and development to mission-driven organizations Notably, we've been working with Drupal for over a decade and we contribute to the project every way an agency can Since 2000 we have been working with some of the most amazing mission-driven organizations in the world And we were founded to do work that matters It's how we attract the clients we want to work with the team we need and it's one of the reasons I joined at in two years ago So what are we gonna cover during our session today? We're gonna look at Ineffective versus effective documentation and how to identify the differences between them We want to set up your writing for success through outlines and planning with preparing for different types of projects And then lastly we're going to take and apply these concepts to existing documentation examples on You know demonstrating how they're going to improve your communication So what makes ineffective documentation? Can I get a show of hands? How many times have you guys picked up a project and the documentation left you with more questions than answers? Hi, yeah, me too great. I'm glad you guys are here So most documentation is written in the hopes that it will help someone in the future Understand a process specific tool or software However, there are several things that can cause your documentation to be ineffective. So let's take a look at what some of those issues might be Identifying ineffective documentation. So here's a short list you can use as a guide to compare your documentation against No documentation This could have been a timing issue or concern over how to start or you've inherited an old project Maybe that just didn't have anything in it No images or visuals Documentation consisting only of text without images can actually make it hard for users to follow along sometimes difficulty searching and navigating Users struggle to find what they're looking for and the current structure doesn't really make sense navigation wise unhelpful naming conventions not following a concise naming structure or using undescriptive names and inaccessible content, do you know if your content's accessible or have you been written with accessibility in mind and outdated content when was the last time your documentation was updated and how do you track this information and The last one I've got is the wrong audience Who was this documentation written for and doesn't support their requirement needs? That's a pretty decent list, but we're actually going to dive a little bit deeper into each one of these items No documentation nothing exists This one's pretty easy to identify Having no documentation is obviously not ideal and usually we find ourselves in these situations It's time constraints budget constraints sometimes confusion over what and how to write even Having no documentation is its own starting point You get a chance to step back and reevaluate the project needs and Follow the outline and rat resource gathering process that we're going to cover later in this presentation No images or visual aids There are a lot of situations where pictures or visual aids work better for explaining a task than just text Images give users a visual cue or an anchor that they can look for while following along with your content Here's an example of something most people are pretty familiar with especially if you presented at this conference Creating a new set of presentation slides using a template on the left hand side We have a snippet of documentation. That's all text-based and somewhat lacking clarity We direct the user to a location with rough instructions of how to complete a task So create a new presentation go to Google Drive select Google slides click conference presentation Okay, we've probably all seen something similar to that However on the right hand side We've actually clarified the instructions and added the template gallery button image by doing so We've created a visual anchor for users that are following along So now when we go and look at it We've got a new presentation slide go to Google Drive select new Google slides click on the template gallery button That's our visual anchor. We can go and look for this and choose conference presentation Visuals like this can actually be key in helping someone follow along with what's being explained And they play a larger role in guides and technical documentation which might include more complex steps Difficulty navigating and searching If you have your documentation in a repository tool such as notion or confluence How hard is it to find what you're looking for? Documentation often utilizes a hierarchy based organization, which is a simple structure for outlining content by groups However, having things deeply nested or buried within other groups makes it difficult to find content navigating and to maintain in the long run To avoid this, I actually recommend grouping your topics together in what's known as a flat hierarchy It avoids groups containing groups When was the last time you evaluated your structure? It's important to review your hierarchy when you're adding new section or Contents to get it to make sure that it actually follows along the flow of your content and In tandem with a straightforward structure It's imperative you allow your users to search for content on their own and provide them with a method of doing so Documentation without any sort of search function is a frustrating experience. I'm sure we've all encountered something at least once I know I've control F throughout a project and been like what am I looking for? Please help me find this But to support your good to search experience. Let's actually take a look at naming conventions unhelpful naming conventions Naming conventions can be a pitfall no matter the type of project whether we're creating headings or labels We want to use descriptive language in relevant and consistent ways This ensures that the labels and headings are meaningful when I read out of context a really good example Is you're jumping around from heading to heading within a document? You can easily find what you want without having to waste time waiting through individual sections We've all done that scan and scroll scan and scroll. Where where is it? In this example on the left hand side It's difficult to scan the options because they all start with similar text and they don't accurately relate to what's being covered within So we've got content structure add content delete content. Okay, cool me user accounts add user Remove user remove permissions Yeah, I think I understand what's going on But when I look at the more detailed names on the right hand side add content becomes adding a content type and remove user is deactivating a user and role permissions turned into assigning permissions to a role Based on that previous list as a user my assumptions of what those sections contained was vastly incorrect Based on what they actually cover This is one of the reasons it's important to use that descriptive language, especially at the heading level Following a descriptive naming convention can not only make your content more searchable But it also makes your content more accessible as well Inaccessible content so having accessible documentation is incredibly important In fact, some of the things we've already covered help make your content more accessible But here's a specific list Highlighting a few important ones that you should keep in mind Adding accurate and concise alternative text on images within your content Support screen readers and this applies not just on the web. So we've got this in your documentation Addressing color contrast for visual elements. This is a big one to my heart Colors should not be the only means of communicating important information to a visual user Those that are colorblind need to have a different way to distinguish information in case color differentiation is difficult for the user to see And this goes for non visual users as well Imagine your document is being printed in black and white Can users still understand what's being displayed? if not Texts or patterns need to be implemented along with color Another option is to a supply a more data-driven approach to this infographic such as adding an accessible table In the example at the bottom of my slide You can see three different pie charts the left relies solely on color the middle and right I've removed the color Saturation to show you the difficulty of differentiating between the sections by color alone on the far right I've added a pattern to the right chart and you can actually use that to visualize and understand and read it And you don't need the color. It's it's that easy So continuing with their accessible content use descriptive link text We really want to avoid vague links such as learn more and click here I know they look great on buttons, but a user should be able to know exactly where the link goes based on the text alone in This top example You can actually we call out for users to learn more with no real context with regards. They're learning about All time off needs to go through direct managers learn more. Okay about what? However, right below that using more descriptive text We realize that the link is encouraging us to learn more about their volunteer programs by adding that text You've given context of the link and users know directly where it's going Emphasizing text within contents pretty common on the web and it's recommended you avoid using Underline text as a form of emphasis because for most of us underline text is a universal sign for a link So instead you want to use bold or italics when you need to emphasize something a Fun trick about this is when you build these habits checking your documentation for accessibility Fun fact it works on your website, too, and if you haven't heard Helping out with screen readers and navigation. It's a great way to boost your SEO outdated content Maybe you already have a bunch of documentation, but aren't sure when it was last written or updated outdated documentation can be a problem, especially if the content's a tutorial or a guide that might have had visual changes Are yours if your system doesn't support version control take a look at a timestamp or the publication date and note when it was last updated After updating your content make any visual dates updated as well This helps your users know they're getting the most recent version of your content We're going to talk about long-term maintenance in a few minutes However, I recommend reviewing your documentation at least once a year You can make this task more manageable by reviewing pieces throughout the year rather than all at once And when you're reviewing your content, this is a great time to see if you've written it for the right audience Writing for the wrong audience. I know thrilling titles Documentation can be confusing especially if it's written with the wrong audience Define your user who is going to use this documentation and has the intended user changed Since it was last written, maybe you've had a change in the office or the titles and the positions have changed Looking beyond who's going to use it. How do they expect to use it? What are their actual goals when they pull up your documentation? Sometimes things get created with good intentions, but they don't actually meet the use case which creates a really frustrating experience We want to address what users expect to be documented and Lastly, do you have a list of people who can provide feedback on your documentation? You want to confirm that what you've created is easily understood by the expected audience Now that we've looked at some ways That make documentation ineffective. Let's take a look at how we can craft Ineffective documentation plan for success. So confidence is key. Well That and good planning. How do we craft documentation in a way that sets us up for success? Thank you. I'm so glad you guys asked What do we need? We need to identify specific needs of a project and any unique things that if not documented could cause problems later Earlier we talked about audiences and here they are again Who are we writing for that's a question that we need to ask early on and Frequently to help align our formatting our project managers and sales teams out there. You guys often write process based Documentation process documentation focuses on the development of a product not the product itself You're outlining a sequence of steps that need to be followed Some examples that you guys will see are timelines and project requirements as a developer I mostly write product based documentation that focuses on a finished product how to use or understand something You see this type of documentation pretty frequently with user guides Ikea furniture anyone Technical architecture and developers. We see it with API documentation and in release notes Both of these are still considered documentation But with widely different audiences meaning the language and the format that we use need to be different What kind of information do you currently have do we have any outstanding resources or documentation to work from? We want to make sure we gather as much information as possible so that we don't duplicate work Are there any specific tools or style guides we need to use do we write our documentation in Google Docs in Confluence notion or some other supporting tool and Last what's the timeline that this needs to get completed by are we writing throughout the development process? Or is this just something that needs to be done by the end of our project all? Of these questions should be addressed prior to even starting your documentation once you know the questions You can actually move on to outlines Creating outlines When you're starting with new documentation, I recommend planning a rough outline using a flat hierarchy Which is grouping topics together where nothing is nested within another group Think about the flow of your content. What does the progression mean? Does it make sense for your users? What might your audience be expecting with regards to your progression? On the right-hand side have actually created a simple outline That's based on a project for both developers and site builders this outline would be used to build out documentation for their new website Please keep in mind that this is on a slide So it's not as detailed or as long as it probably should be but you can quickly identify the sections and follow the flow of content At the top level we have relevant hosting information Followed by developer specific workflows and then configure management This flow somewhat mirrors the development process of a site. You're selecting your hosting provider We're creating and developing the site itself and then building out the individual configurations that make the site unique While this is a short example It's easy to follow along with and determine roughly what each section will contain throughout the planning process Now if you guys are editing existing Documentation take note of your current structure and flow of the content Does it make sense as is or could simplifying your format improve readability a really good exercise? That I've done is taking a piece of documentation and cutting it down to just the basic outline headings Very similar to our example here. Does that structure make sense and hold up in that format? If it does great awesome, you guys are top 10 if it doesn't though, that's time to consider editing So what makes clear communication? We've gathered our information. We've made a rough outline. So it's time to write But what does clear communication actually mean or look like be concise? Explain how things work but do so in a straightforward format if you're writing something that's detailed or complex try breaking it down Into smaller steps you can do so and transform your content Something that might have been difficult for users to understand into these smaller components that they can comprehend and follow along with Don't repeat yourself or dry. So as a programmer This is something I strive to do all the time writing code and documentation in a specific way that helps ensure We don't end up with duplicate work This ties back to our initial step of figuring out what we needed by spending time Then to research what already exists we can alleviate duplication Active voice versus passive voice So this is not something that people necessarily think about when writing documentation But you want to actually utilize active voice as much as possible It helps make things clear to the user that they're the main acting party with less room for misinterpretation Using active voice in your writing gives readers a sense of ownership of the actions that they need to take when reading through your Documentation it really helps create a clear image in the reader's mind of what's being described Avoid using unclear words. So this was pretty self-explanatory But if you find yourself using vague terms to describe something It's time to reevaluate what you're describing or maybe get some help and Lastly if you have a style guide follow it, please if you don't have a style guide That's totally okay We want to try and keep your styles and formatting consistent and I've actually got some examples of some formatting styles Setting standard Formats for your writing style fonts and other things within your content is imperative for success when it comes to large-scale Documentation well, this might seem like a minor thing It's important to have that consistency when you have a lot of different people contributing to your content That's pretty common with an open-source world like Drupal Your formatting doesn't have to be fancy or innate just consistent on the left again We've got an example of documentation with varying styles and formats the first thing we see as browsers is underlined Well, that's a header and not actually a link So it doesn't make sense and it's an accessibility concern as we keep reading through this content the font changes The size change. There's two different list formats once using numbers That doesn't actually make sense because it's an unordered list Overall, this left-hand side is busy and hard to read But we look at the right-hand side and the only changes is making a consistent type base font size and list format By doing so we made it easier for the user to read and understand without taking away from what's being documented Here's an expanded example of using basic text styles and formatting to create easy structure within your documentation There's a clearly defined header body text and lists throughout this example There's one font style that's used we have a straightforward hierarchy within the content and the lists have appropriate formatting Whether you're creating document in specific tools or writing a markdown following a basic format like this helps give you visual consistency Speaking about tools there are so many different ones out there This is just a short list This is not all of them of things that you might use while documenting Confluence and notion are great for supporting large-scale documentation that's shared throughout an organization or a team They allow you to create structure and organization Within your documentation in a way that best supports your specific needs Another option I've got up there is Google Docs Which I've actually used a bunch when creating technical documents that I need to export as a PDF for a client or another team member and as a developer specifically using tools supported within our IDEs such as PHP storm dot comments that can automatically be generated or VS codes many open source documentation extensions Using IDE supported generators We can make documentation easier by providing that initial structure that we can then go back and edit and expand upon So this is a step a lot of people don't have when you're writing documentation here review and testing We've written our documents. It's time to take a look at them When possible I recommend having documentation reviewed by other team members ideally some that are not familiar with what's being documented a Quick test you can do you is have two other people read through your content and see if they agree on what's being communicated Was it easy to understand? Does it make sense as a standalone section? This style of testing is simple But it allows you to get feedback ensuring that the goal of your documentation was achieved and it can help identify any confusing language or important missing steps Before finalizing your document take a few minutes and review that style and formatting throughout or consistent and follow any expected guides Once your documentation has passed testing and review you have to plan how to keep it maintained If your team doesn't already have a long-term plan I'd recommend developing a process and I've got a few suggestions here to help long-term maintenance When looking at who's gonna maintain the documentation? Break things down in a way that makes sense a few examples would be by project or supporting team Ideally initial ones who created the documentation would be able to maintain it, but we know that that's not always possible I recommend looking within your team to see who might be the best fit If you have a large amount of documentation Starting this type of process does not have to be done in one year. In fact Don't Trying to do so will make you and your team overwhelmed. We want to make this better for your company better for your product This is why we're here. I like to break my documentation up into three categories I create a list of content that I would consider evergreen or something that changes rarely Usually I put this on a review schedule of every one to two years. I trust this content will stay fairly consistent For process or policy documentation. I actually recommend reviewing that at least once a year It's a good habit that helps make sure your content is up to date especially when you guys have new hires you get access to relevant information and Another benefit that a lot of times people don't think about is it encourages your team to review? process or products for improvements and effectiveness it makes you go back over things and question Oh, is this the best way to be doing this and The third category is any kind of user guide or something that might change frequently within your organization for these documents I recommend reviewing about every six months The first few times you guys review through your content There will be instances where you can remove or rewrite things But as you make this practice more consistent, it becomes a lot easier to manage So developer specifics much of what we've talked about thus far has been widely applicable as a whole which is great But we're gonna focus for a second on a few developer specific components Read me files. I would love to get a show of hands from the developers How many of you have forgotten to add a read me file on a recent project? Don't feel bad I've been guilty of this too and sometimes we just want to get into a project and we get started right away And we're like, yeah, I'll go I'll go back and add this Read me's are actually really useful, especially in our open source world They provide a quick introduction to your project and can answer questions that people might have when interacting with it But who is this file actually for? First and foremost you're writing for yourself Even if this is a personal project that only you will ever see a well-written read me can help keep you accountable for your goals When revisiting a project after a long time, it can help remember the specifics that you might have forgotten Ideally preventing hours of struggling But beyond ourselves, there are additional people who might use our read me files such as other developers contributors or users Groupal is an open source project and lots of different people contribute to it. So having a read me is a must It helps reduce the time and effort of each contributor and allows them to learn about your project in a consistent place Speaking about specifics. What should we actually include in a read me? I've listed a rough outline here, but you can always add more sections based on the details that you want to include Ideally your read me's when include a table of contents that helps users quickly navigate through your file and find what they're looking for You got to have that search ability piece an introduction or an overview section that outlines your project Any required modules that are needed or specific libraries that we might need? This one's super important. I definitely needed it more times than I care to admit instructions on how to get started or Actually install and use your project I love to add a troubleshooting an FAQ section. This one's not necessary But I like keeping a list of things I've encountered or that other users might find helpful such as known issues and ways to solve them Reading your contributors or maintainers. We want to highlight all the hard work that people have put into this project and Lastly outlining any future goals or features that you have planned it helps people find ways that they can contribute to your project change logs a Change log contains a record of chronologically ordered changes for each release of a project That is a fancy way of saying we put the most recent changes at the top and the oldest at the bottom We use change logs to make it easier for users and contributors to see exactly what changes have been made between each version of a project They should be readable and easy to understand by anybody Can change logs be ineffective? Yes, especially when we're talking about readability you want to avoid using commit messages as change logs And I've had reason why the purpose of a commit is to document a step in the development process But the purpose of a change log is to document noteworthy differences often across multiple commits and you this is a way to communicate those Clearly by using commit diffs You're creating a kind of confusing document that can be hard to follow and sometimes filled with unnecessary messages This is a great time to think about writing for that specific audience and what they might be expecting to see in your document I Avoid change avoid the commit logs. So what should it actually include? When you're structuring your change log There isn't any official format that you need to use but on the left. I've listed one that I would recommend Start with a definitive timestamp or date date formats vary throughout the world And it can be fine hard to find one that feels intuitive to everyone the advantages of dates formatted like 2022 April 28th is that they follow the order of largest to smallest year month day done very straightforward This format doesn't overlap in ambiguous ways with other dates and it makes it a simple and consistent way to track things Next we want to add features focusing on any of the cool new things that we've added to the project and what it does Followed by changes that might have been made to existing code Specifically highlighting any known breaking changes or you can consider making that its own section and Then we want to list any deprecated code or features so that other developers we can apply accordingly and adjust our own projects and Lastly under all of that is the previous comments from our change log because once again We are always adding to the top of this file on the right hand side I've got an example of a change log from a pantheon code base and we'll see that the sections are clearly Defined and easy to understand at the top is a header in date and then we have three main sections added Changed and removed each of them clearly stating the difference since the last change was made Let's dive a little bit deeper into code itself Commenting code this might seem like a simple question, but does anyone have an answer? When should we write? documentation oh I love always As a developer I personally think the best time to craft documentation is as you're writing your code in those moments you have the most understanding and Comprehension as to why something works the way it does you can always go back and make edits as things change and evolve I Recommend writing with new developers in mind You never know who's going to work on a project after you and we want to set them up for success This is especially important in our open-source community as we have a diverse group of developers And we want to ensure that what we have can be clearly understood no matter who's reading it We were all new devs once So thinking about clarity What kind of commenting and formatting tools can we use? Drupal recommends using code sniffers to verify if code meets Standards a common one you'll see is PHP code sniffer These are great because they help your code remain clean and consistent throughout the development process Another great documentation element is doc blocks Using a doc block you can document the function of relations between all the things within your code This is an important tool that can help other developers know what a function may need and understand what its purpose in your code is Doc blocks we're going to dive more into them real quick Specifically you can add summaries explaining how something works tag parameters variables return objects and much more Here's an example from Drupal cores doc block Drupal cores block module Excuse me and at the top of this block we see a brief description of what the function actually does It appears to call a method on a block which afterwards it reloads the page There are several tags listed within the block tags are a type of specified information about specific elements You can identify them by the at symbol in front of them If we look at the second listed at per RAM within this example It tells us that the argument named dollar sign up is a type of string and has a description of what the functions actual position with the argument is in this case the dollar sign up is an operation We want to perform on the block in the very Last line it calls out the return aspect of this method which appears to just redirect to a piece of the redirect piece of the function Could we determine all of this functionality with the code alone? Eventually yes, but the true benefit of the doc block is that we were able to quickly break down and identify what the intention of this method was When writing more complex code having doc blocks good method names we can identify code sections quickly Which relates back to that search ability piece regarding our effective documentation now? I've gotten this question a bunch how much is enough When it comes to documenting something that uses a framework like Drupal I always like to make sure to include a link relative to what I'm documenting So a really good example, and I'm sure other developers in the room have done this I'm following a specific guide or solution that led me to code something in a certain way I Like to add a comment with a link to the document that I was following By doing so I've ensured that others who interact with my project months weeks years later Can understand why a decision was made or what my original intention was by creating it that way? Highlight unique things to your project a good rule that I personally use is if it would take another person 10 to 15 minutes to figure out how something works by reading my code Just document it That can either be adding notes to a documentation tool or read me a file or even with inline the code itself Review edit review again This is why the review step is so important when you're creating documentation or writing the software It can be easy to think something explains itself. I've done this a bunch Think about how if you had to come back to this project weeks from now months Would you be able to understand quickly what's going on or better yet? What if a new developer wants to be involved in helping support your project? Can they even understand what the code actually does without spending hours of their time trying to get started? When writing we want to be explicit. It's either easier to over explain than under explain during the initial process You can always go back and remove stuff and simplify it down later during the review process Okay, you've stuck through this Existing documentation throughout this presentation. I am sure there are some of you that are thinking I already have documentation How do I make it better? Well, let's take a look I've actually crafted a few examples that we can walk through and see how applying the concepts we've talked about Improve the clarity and effectiveness Here's a basic example showing users how to add their email signature anybody who's got gmail. You've probably seen something like this Let's identify some of the issues here So everyone's gmail should match the template below Employees may need to copy and paste from someone else reach out of help as needed. Okay. Hmm Well, this example is missing a descriptive header to identify the section Something interesting. Did you notice the entire document was written using a passive voice? Employees may need to reach out from someone else reach out. Okay There's a reference to copying the signature from others But the code should have just been included in the first place and the last line says to reach out for help But doesn't actually point the user in a direction of who to even reach out to Not not great now that we've identified what needs work. Let's take a look at applying what we've been talking about. Oh This is already a lot easier to understand We've added headings So we can define the content and allows users to scan what they're looking for how to update your gmail gmail code perfect We switched now to using active voice giving the reader ownership of reaching out if they need assistance Inside gmail navigate to general settings roll down to the signature section copy and paste the code snippet below Please reach out to Steve if you need assistance I read that and I feel that these are steps. I will be acting upon The call to action has been replaced with someone actually to contact and their email address readily available And instead of hoping to find someone with the code. It's now included in the documentation You guys are gonna find as you review your documentation These edits are easy to make and they have a pretty big effect While there weren't many changes in this example. We made four They made the content that much more useful to our end user So here's a quick example of documenting an organization's workflow with regards to branches and database polls Create new branch off main push code changes back to that branch merge to dev Once dev approved merge into staging and after QA Approval deploy changes to main no databases go backwards and dev do not override main database well Technically that documentation covers what was being asked, but it's not really clear and Not easy to understand. So what makes this ineffective? Well, once again, we're missing headings describing what the section contains and if you're unfamiliar with the workflow It's hard to visualize what's actually being explained They're not using descriptive language and a lot of jargon that if you're new to the company you may not know and The note at the bottom is not clear and I'm not really sure why it's in this section So let's look at an updated version. Wow That's pretty different. Here's an updated example with a few few changes We added a section header making it easier for users to quickly identify what this content is about We added a diagram and this is providing a visual example of what the text is explaining now I'm not saying everything needs an image But they can be helpful for people who learn visually and are a powerful tool when creating documentation to teach something We updated the content in each of the steps in a way that clearly communicates So let's take a look new feature branch should be created off production code base main During development the feature branch may be merged into the development branch for dev testing When dev work is complete merge the feature branch into staging for quality acceptance and testing After testing and approval the feature branch can then be merged into production note During the development pull databases backwards towards the relevant environment never pull databases forwards This protects the production database from being overridden. Wow. Okay. If I wasn't a dev I could actually follow this and looking at the visual next to it I can see that the feature branch goes out to those environments and the databases go backwards a lot of this we modified But it makes overall more sense and is easier to read. I Had to give you a code example. So We talked about code comments earlier and here's an example we can approve upon It appears that we're missing a summary of what this function's purpose actually is So we're left to figure out with a few clues remaining the name of this function Format using filter. Okay. This tells me that some this is a formatter with some sort of filter kind of helpful in the dock block I see that the dollar sign filter format is being passed in and It looks like maybe a boolean is being returned and We're determining access if the format was used as I keep reading Okay, the rest of the code the dollar sign format filter format is To get an array of filters and we seem to be using a list of filters to check if one exists and the status And then using that status We return true. I Actually asked a couple other developers previously what they thought when they saw this function Yeah, the results were really all over the place with how people thought this worked and That's a lot of questions for a function that is as short as this like this is the whole thing That's it. So how can we improve this? Amazing we added a dock block We introduced with a brief description of what this function actually does now We can quickly understand that the function checks access based on a media filter Media embed filter status on the text format. Okay, awesome Having that one line alone cuts down on the bulk of questions and guesses we made looking at the code previously There is now a description for the filter format parameter Explaining that it's a text format. We used to check access with and in addition to the dock block changes We updated the function's name Format uses media embed filter to be more explicit regarding what the purpose that this function serves all of these changes improved clarity Searchability and understanding of the single function fun fact. This is actually an example from Drupal cores media filter controller Writing documentation often goes beyond just writing inside code bases And I really hope that these examples have given you insight regarding how you can apply the things we've talked about in your own work Whenever you're writing remember these three ideas Identify what your documentation needs are Outline them in a concise and straightforward format and write using clear communication Don't be afraid to edit and review your work documentation is a living concept as You continue to build good habits the better off your projects and the open-source community will be If you wanted to see additional resources or information regarding how to craft more effective documentation I've listed a URL there and There's also a QR code. I'll leave that up for a few seconds. Feel free to snap some photos and Atten is doing a giveaway if you haven't already been by our booth You can scan this QR code to win a Apple iPad or AirPods and we will be in touch if you guys win Feel free to come and see me at 103 And pick up this year sketchbook So I didn't click next on this line. Okay There it is feel free to scan that and win an iPad I'll give you guys a couple seconds now. I see all the phones coming up. This is great So thank you guys so much for listening. I hope you enjoyed this presentation as much as I enjoyed giving it Documentation is a really big hobby of mine. I've got a couple minutes that aside to answer any questions. You might have Hopefully I can answer them, but thanks. Oh Yeah, I think we have a mic over here in the middle Yeah, so the question was have you ever had to write documentation for another client That's basically the same as what you've written before So I actually created it's like a 40 page document. I am a nerd and I Wrote for each of the hosting providers each of the different local environments And I copy and paste it and I will modify something like that for the client that I'll customize it for their specific needs But I'll keep it in like a generic repository so everyone has access to it So you're not writing the same thing a million times But you want to provide your client with something really helpful to help them understand so it can cut down in your work that way Yeah Thanks for the talk I was gonna ask if you knew of any tools that would kind of help to bridge the gap between Developers and content editors either within the UX that they're creating or you know outside of it as well Tools in terms of documentation. Yeah, exactly So if you're building as a developer a lot of times you build out user experiences that the editors have to interact with and sometimes It can be difficult to just compile everything that you're trying to communicate with your field in a field tip or like a little hover You know a hover tip that pops up So I was gonna ask if there was any more robust tools that are out there that would give a little bit more information to editors that Would show them what to do with the Fields or whatever it was in the UX that you're creating for them. Oh within the site exactly You know what I don't know off top of my head, but other developers that sounds like an amazing Contrib module we could make I'm just saying I use a lot of times when I pass sites off to people if they if I know I'm working with content editors I love giving people screencasts or voiceovers some people are visual learners some people work great with documentation But in terms of in line the site, I don't know anything off top my head Okay. Hi. Thank you for I don't like my voice at all. Wow So we're we've set up like a ruling release cycle for our main website and I'm trying to get Documentation updated every time we basically release a new feature. So setting up our review process on each milestone or each release and Having people kind of review what we currently have and adding any documentation for that feature What do you think about that? And do you think that's too? You think we're Updating it too often or whether that fall in would that be like a user guide or what would you generally recommend? Absolutely anytime. So the question. Oh, I think people heard that I would I would absolutely continue to write it as you guys release new features Think about as a developer a lot of times we think about okay, I made this new thing Here's what it does but think about the people who are using it your content creators your site builders They may not know the intricacies creating and reviewing that content every time your documentation is a great way Not only are you keeping it up to date, but you're you're really helping people out Especially if you had someone new join your company, too. They can go back and see Every individual piece that you've updated. So I think that's awesome Yeah, I'm it's a lofty goal, but you know you mentioned every I think half a year six months or whatever for like a user guide and Yeah, we're hoping we can do that, but I just want to know if it was too often No, I don't think so and to keep in mind that these are don't go and implement all of the things immediately Like if you get back home, you're like we're going all our documentation right now people will cry I Tried it once don't do it But by doing it in those small pieces you're not you're building a really good habit And I totally think that if you can get that down and continue to do it It'll just become second nature and you'll find ways that it's easier to continually be like, oh, this is what we changed This is what we changed and it's great for record-keeping So, okay. Thank you. Yeah, thanks Any other questions do you find that it is more useful to link off to Supporting content more often than embedding it all within the same So you you gave an example where there's linked off of find out more about how to do formatting options What is your When do you make the decision on go find out more information about that over here? I'm not gonna fill out this form with that. Yeah, totally so that'll be our last question it is a lot of the times if it is a really long tutorial I'm following or Okay, how to set up and configure a custom module that someone else has posted then I'm Probably gonna link to it just so that you can review it But if it's something that you know the gist of it and you don't think you know The link is useful for them to have then just put the highlights of hey This is why we created it our original tension was this that's good enough I just if it's a really long like four pages of Customize this PHP function to do this specific thing. That's that's when I link it But I think I've run out of time. So thank you guys so much for coming and I hope you learned something about documentation