 Thanks for coming. I'm gonna be talking about Drupal's documentation from a bunch of different angles, mostly kind of a state of, the state of documentation. Where are things right now? What are we trying to accomplish in terms of making it better and how we're going about doing that? My name is Joe, or EoJTheBrave on Twitter and Drupal.org and pretty much everything on the internet where I could get the name, which is pretty much everywhere because it's just some random characters and it's awesome. I'm a member of the Drupal Documentation Working Group. There's a handful of us that try to help shepherd Drupal's documentation, make sure that good things are happening, that there are policies in place, that there is someone that can answer questions when they arise and that kind of thing. So I do that. I'm also actively contributing to Drupal's documentation and have been for quite a while. For my day job, I teach people Drupal. I work for DrupalizeMe. We produce training for Drupal, which of course dovetails nicely with documentation. So I have, not only do I kind of do that professionally, but I have a lot of interest in it because having good documentation makes it easier for me to learn how things in Drupal work so that I can help teach other people how they work. And just kind of personally, I'm really passionate about documentation because I feel like it's an important part of how we improve and grow the Drupal community is by having quality documentation so we can help to onboard new members in our community, whether they're learning how to build a site for themselves or how to contribute to Drupal or whatever it is that they're trying to get involved with, we can make that process easier by having good documentation. So this presentation, I'm gonna talk a little bit about like what documentation is and the various types of documentation that we have for Drupal and why each one of those is important. And then I'm gonna talk a bit about some of the changes that have been made to drupal.org and the infrastructure for supporting documentation over the past about two years now and sort of hopefully educate people about those changes and how we're hoping that they'll make it easier to maintain documentation and improve the quality of our documentation. I'm also gonna talk about the Drupal eight user guide initiative a little bit and then finally, I'm hoping to have a little time at the end to kind of discuss any questions that people have about these tools and also to hear about either things that are frustrating for you about documentation and talk about what we might be able to do to improve them. I say we a lot in this presentation. I'm like, yeah, we did this and we did that. And I just wanna take a moment to acknowledge that when I say we, I'm talking about a lot of people who contribute time to improving Drupal's documentation and working on it. There are literally thousands of people that edit content on Drupal.org and help make it better. There's also a handful of people who are really, really involved and help out a lot. Jennifer Hodgden, Drupal's sort of official documentation maintainer does a ton of work. A lot of it is behind the scenes and you don't necessarily see it but she does a lot of work and it's really awesome. The Drupal Association, Tatiana especially, has done a lot of work recently in order to help improve the tools on Drupal.org. So it's important to just recognize that there are a lot of people involved in this. I certainly didn't do all of this work. Mostly I complain about things a lot and then hopefully inspire other people but I'm like, yeah, this is bad. We should fix it and then other people are like, yeah, we should fix it and I'm like, yeah, good work. So there's a lot of people that help contribute to documentation. Hopefully some of you do and will in the future. So when we talk about documentation, one of the things that I like to think about is why do we have documentation for a Drupal? Why is having that documentation important and what is the sort of really high level goal? And for me, the high level goal of Drupal's documentation is to help people transition along this pyramid of sort of expertise within Drupal. Whatever skill it is they're trying to learn, whether it's being a Drupal contributor or using views to create a list of nodes on their site. People kind of start out as a very low level. They don't know a lot. They're a newcomer and slowly transition through these different skill levels. Primarily the documentation on Drupal.org is focused on kind of this learner to skill transition. Helping people who, they've already evaluated Drupal. They know it exists. They have a rough idea of like, yes, this is probably the tool that I'm going to use. Drupal.org tends to have a lot of tutorial-like content that will help walk people through. I know I want to use Drupal. I know I want to build a view. Here's the documentation on how to do that. Other things like api.drupal.org, which is kind of more reference documentation tend to be a little higher up in the chart here. It's more of the like, skilled to expert. You have to have enough knowledge already to know that hook form alter is a thing before you would even go and look up the documentation for hook form alter. I also think it's important to talk about documentation and continue to improve it because it is important in the way that people perceive Drupal. So when people, you probably do this all the time, like every day you're working on a web project and you need to go evaluate some module on Drupal.org to see if it's going to solve your particular problem. So the first thing you do is check out the documentation and just try to get even just a rough sense. Like you read the project description and try to get an idea, is this gonna do what I need it to? And hopefully you can learn enough about the module or the project that you're evaluating just by looking at some of the high level documentation to say, yeah, I don't know exactly how it works, but I'm pretty sure this is gonna solve my problem. And people do that with Drupal all the time. They'll come to Drupal.org. They'll be like, I've heard of this Drupal. I would like to know, will it help me build the website that I'm trying to build? And currently they come to Drupal.org and they go into the documentation and then they navigate down, down, down, down, down, down, down, down in the black hole and we lose them and then they never come back. So we're trying to make that a better experience so that when people first come to the documentation and start reading it to get a sense, like, oh, I get an idea of what Drupal's capable of and that sounds like what I'm trying to do or that it may work for me. So setting a good first impression is important. There are a couple of different types of documentation at work here. There are tutorials, which are sort of like step-by-step instructions, a little bit of hand-holding. I would like to add a field to a content type. Step one, navigate to this screen. Step two, click on this button. Step three, you've got a field. There is topical documentation, which is a bit more, I would like to understand, not so much how to perform a specific task but why I would do things in a certain way. There is how to use the field API to add fields to a content type and why you would choose to add a specific type of field versus another type of field. It's like that distinction is, I think, important when it comes to learning how things work. And then there's reference documentation, which is like looking up the parameters for a method on a class or if the variables pass into a function. This tends to be the api.drupal.org stuff. For the most part, I would say drupal.org in the handbook section are tutorials and some topical information. And api.drupal.org tends to be some topical information but primarily reference documentation. I think this is important to keep in mind because people use different types of documentation in different ways depending on how far along they are in the process of learning drupal. This is kind of my rough approximation of the path that I think people take when they're learning drupal. So you've got to, essentially, you're like, you've got some skill that you're trying to learn and a goal that you're trying to attain will call it. I'm trying to learn drupal so I can get ready for a job. And in the process of doing so, you need to gain enough competence in drupal that you actually know how to use it and you can make use of the tools but you also have to have confidence in your ability to do so. And so when you first start out, tutorials are really useful. You've got this kind of like hand-holding honeymoon phase where basic concepts like how to add a user are really well explained in a tutorial that holds your hand all the way through. And that's really great because it increases your confidence really rapidly and it makes you think, wow, drupal is really great. I can accomplish a lot with drupal relatively easily by following this step-by-step tutorial and then all of a sudden you have this painful realization that like it's actually a lot harder to do things with drupal when you can't just follow the step-by-step tutorial and you need to kind of make decisions for your own. And so you kind of like fall off this learning cliff. It's sort of like what happens is that the tutorials do a really great job of introducing you to a lot of concepts and now you get into a situation where you've got thousands of concepts that you need to understand how each one works. And this is where topical documentation becomes important. It explains kind of the why of various elements of drupal. You know, it's sort of like a tutorial can teach you how to implement a hook that teaches you the process to follow to add a hook to your module, but it can't necessarily teach you which hook to implement. So the topical documentation is all about, wow, do I use hook in it or hook boot? And what's the difference between the two and in which scenario would I use the different ones? And eventually reference material becomes useful to you. So api.drupal.org and things like that, but you have to have enough base information already before api.drupal.org is really useful. Like you have to know that there is such a thing as a plugin and that that's probably what you want to implement before you go and look up the documentation on how to implement a specific plugin type. And I kind of keep this in mind specifically because I think that we could do a better job of providing documentation for sort of the tutorial and topical side of things and people who are earlier on in the experience of learning drupal. In a previous keynote, Dries put this slide up. It's information that he collected from a survey that he did where he asked drupal developers and users who should drupal favor when making product decisions? So basically as a tool to be able to decide should we do X or Y? Who should we keep in mind when making that decision? And overwhelmingly people voted that we should keep content authors in mind. Like that should kind of be our focus when it comes to making decisions about the features that we're going to add to drupal and that kind of thing. And I thought this was really fascinating because it sort of ranks things as content authors first and then site builders and then back-end developers and then sorry, poor front-end developers. We'll keep you in mind, I guess. But what's interesting about this is I feel like our current documentation is sort of the exact opposite of this. We do a really good job of providing kick-ass documentation for back-end developers who want to look up whether or not the parameter being passed into a method is a string or an integer. And that's sweet, like I'm there and I need to do that a lot. But we don't necessarily do a great job of providing documentation for someone who's trying to figure out like what's the difference between a select list field that is an integer and a select list field that is a text and when would I choose one or the other? But that stuff is really important. So kind of keeping that in mind. And then I mentioned api.drupal.org and like I said, I feel like we're doing a really good job with the reference documentation. So for the most part, I'm not gonna talk about it. I feel like api.drupal.org is in a good state. We continue to make improvements to it and we should and that's awesome. For example, it now works with minor versions of Drupal 8 so you can see the documentation for 8.1 and 8.2 and 8.3, we've added better navigation so it's more easy to navigate things like classes which is important because Drupal 8 has a lot of them. Syntax highlighting has been added. api.drupal.org is indexed by solar now so if you go and search the documentation on Drupal.org you'll also get results from api.drupal.org so there's a lot happening. But mostly I'm not really gonna talk about it anymore than that because there's a lot of other I think low hanging fruit that we can work on and should work on before we obsess over api.drupal.org too much more. Okay, so over the last couple of years by being part of the documentation working group by working on documentation, by having the opportunity to talk about it at conferences like this and get people's feedback and then also based on work that the Drupal Association has done with user interviews and research with regards to how people are using the documentation on Drupal.org, looking at Google Analytics and that kind of stuff. We started to identify things that we thought were some of the key pain points of Drupal's documentation that we wanted to try to address and improve. This isn't everything but I feel like this is kind of the most important ones. In no particular order, one of the things that we struggle with on Drupal.org is that there's a real lack of curation and review of documentation. The nature of a wiki is that anyone that can go and edit it. So anybody that has an account on Drupal.org can click edit and make changes to the documentation. And that's really awesome because it encourages people to contribute and allows you to do so. But it can also be tough because it means that those changes aren't necessarily reviewed. So there's no one coming along saying yep, the thing that you put in there is correct. The documentation you wrote is right. And it turns out there's a lot of documentation on Drupal.org that's almost right. And there's a lot that's just not right. And there's a lot that's really great. Compare that to, for example, the documentation that goes into Drupal core and ends up on api.drupal.org. Every single word of that documentation is reviewed generally by multiple people before it gets added to Drupal core. And so you know it's going to be accurate. It's consistently written just by virtue of the fact that it goes through that process of review. I also think that having subject matter experts sort of curate sections of documentation and perform that review might actually enable more people to feel confident in clicking edit and making changes to the documentation. One of the things we hear from a lot of people is they're nervous to click edit because they're worried that their update to the documentation might not be correct. And so if you click edit and you submit something and you know someone else is going to review it for accuracy, it's a lot easier to feel confident and comfortable making a mistake because you feel like someone will hopefully correct it. You've probably been to pages on Drupal.org where it's like, this is the guide for how to theme a menu. This is how you do it in Drupal 4. This is how you do it in Drupal 5. This is how you do it in Drupal 6. This is how you do it in Drupal 5. This is how you do it in Drupal 7. It's like, ah! They're just kind of a mess, right? And it's either that or there are places where there's tons of duplication. It's like, this is the page for how to add a menu for a Drupal 4 and 5, and this is the one for 6 and 7. But there isn't one for Drupal 8. So you just go find the Drupal 7 one and hope that it's close enough. So the versioning thing is a bit of an issue with our documentation. Organization and findability. So right now, the documentation is a really nested book structure on Drupal.org. It's just kind of like, you know, it's like writing JavaScript. All the code just goes down into the side, right? Like our documentation is basically like, do-lu-lu-lu-lu-lu-lu-lu-lu-lu. And then you get to the end and you're like, well, I don't think this is what I want, so you gotta go all the way back up. You're like, du-lu-lu-lu-lu-lu-lu-lu-lu-lu-lu-lu. Nope. So there's definitely opportunity for improvement there. Translation, it turns out like there are people that use Drupal that speak languages other than English, so it would be great if we could provide quality documentation for them as well. And right now, that's really difficult to do on Drupal.org because there aren't the tools to do so. What we've seen is that a lot of communities that want to have translated documentation will start up like a copy of Drupal.org and they'll copy and paste pages from Drupal.org and then they'll translate them into whatever language. And that's useful for that community, but what happens is those pages, like I come back later and I fix the documentation that was wrong on Drupal.org, but now the translated version somewhere else that I don't even know about is wrong, but they also don't know that I changed the version on Drupal.org so they don't know that they should update theirs and you just end up with a lot of, there's a lot of difficulty around that. It's also like, right, Drupal documentation, it's like there's so much of it, it's kind of never-ending and the prospect of translating that is terrifying. There's like 10,000, there are 12,000 book pages on Drupal.org that provide documentation and the idea of translating that is a little bit scary. We consistently hear from people that use Drupal's documentation that it's really hard to ascertain whether or not a page is up-to-date and accurate. And so, which means that people don't trust our documentation, which is unfortunate. It's hard to feel confident when you come and read a page and it says, this is for Drupal 4.7, but it's in the Drupal 8 section and it's like, it still applies, don't worry. And then there's like a last updated date and that's kind of it. But, and that's the last updated date helps a little bit if you know to check it, but all you're really doing is checking to see has it been edited recently? And it probably has and it was probably somebody fixing a typo, not making a substantive change to the documentation. It's probably still the same page that someone wrote like five years ago. And there's really no way to confidently know whether that's up-to-date or not. This is actually also true of documentation that occurs outside of Drupal.org. A lot of people write blog posts that provide sort of topical documentation. Those blog posts have a date on them. But it's, again, it's hard to know whether or not they're actually up-to-date and for a current version of Drupal. This has been particularly bad for Drupal 8, which was in development for such a long time. There's a lot of content out there right now that's like slightly wrong because Drupal 8 changed over time. And it's hard to know when you're reading those blog posts, whether they're accurate or not. So if you're someone that writes a lot of blog posts about how to do things with Drupal, one of the great thing you can do is try to provide some kind of indicator to people reading it whether or not that content is up-to-date and accurate, please. Our community does a really, really good job of giving credit to people who contribute to developing Drupal, primarily people that can contribute code. We have lots of tools in place that make it possible for us to do things like create a sweet word chart of everyone that contributed something to a module or figure out how many commits somebody made and give them credit and allow them to credit to a client or to their employer. And there's a lot of tools like that in place. There's a lot of work that people do for the Drupal community that isn't code. Documentation is one of those things, but there's also like all of the people that help volunteer at an event like this that organize regional events and that kind of thing. So finding ways to provide them with the same kind of credit that you would get if you wrote a patch, I think is an important problem for us to tackle. And finally, there's just an issue with consistency on Drupal.org. I feel like I don't need to explain that to you. You could go look at any page on Drupal.org and you would feel the same way. So that's the type of stuff that we're trying to address. So now I wanna walk through two of the ways that we've approached solving those pain points. First of all, I wanna talk about the changes that have been made to Drupal.org and how we're, I guess sort of the new world order when it comes to maintaining documentation on Drupal.org. So we're gonna be talking about Drupal.org documentation. It's basically anything that you find when you click on the documentation tab in the top menu on Drupal.org is kind of anything there and below is what we'll be covering here. This section in particular, when I say we, what I really mean is the Drupal Association. They've put a lot of time and effort into trying to better understand how people use the documentation and the tools on Drupal.org and then working with the community to help improve those tools. So, yay, Drupal Association. So the Drupal Association primarily went through a process of doing a bunch of research and trying to understand how people use Drupal.org and its documentation. And I point this out because I think it's important to remember that we didn't just make this stuff up. Like, we weren't like, hey, this is a problem and now we're gonna make up an answer to it. It's like, we took the time to talk to the people that are using Drupal's documentation and ask them how they're using it and what's tough for them. And we also took the time to talk to people that maintain the documentation to get an idea of what did they want to improve. And it's important to remember that because change can be really hard sometimes. And especially in a large open source community like Drupal's, people tend to be really opinionated. And when you come along and you make a change, someone's like, but you change that thing that I built like 10 years ago and I really liked it. And it's like, we really liked it too, but it's 10 years old and we needed to make some changes. We didn't mean to offend anyone or to step on anybody's toes. The goal is to improve Drupal for everyone. So the process was doing some work with the Drupal Association and Forum One to do a content strategy audit for Drupal.org. Beyond just documentation, they basically read all of Drupal.org and then decided, how can we improve this? I'm pretty sure that's how content strategy works, right? You guys read all of Drupal.org. You print it out in three ring binders. I'm sorry. So they did that work to get a sense of what content exists and how that content is used and make recommendations about ways that it could be better organized. There was a lot of work done with the Documentation Working Group to prioritize existing issues with the documentation. Those of us that were on the Documentation Working Group basically went through all of the issues in the Documentation Issue Queue, trying to get a sense of where are the commonalities? What are the things that people are really pushing for? What are the things that people have been really pushing for like 10 years and we've primarily been saying, yeah, yeah, yeah, we hear you and we should address those. And so we were able to come up with a list of things that we thought were really important to try to solve and then provide that list to the Drupal Association who's doing the work to make the updates to give them a sense of like, if you're gonna put time and effort into this, these are the things that we think you should focus on first. There was a lot of user research done, both like analyzing Google Analytics and various other data in order to get a sense of how people navigate through Drupal's Documentation. Hint, they don't. They actually just get there from Google and then read the page they're looking at and then leave. But, and then talking to people who are using the Documentation, like actual user interviews say, what are you doing with the Documentation and how is that working for you? All right, cool, I heard what you were saying and I came up with this wireframe and some mockups of how this could be better. Does this solve your problem? Does this make it better? And some back and forth with people that use the Documentation in order to try to get some real world experience and understanding of how we can improve it. So they did all that and then like how this is like, like one word little line up and then they built it which took like a year and a half or so because it turns out it's a lot of work. And now all of the tools are built or at least in a state where we can start to use them and the current status of things is that we're migrating the existing Documentation, all of those 12,000 some nodes into the new structure that was created. I'm gonna talk a little bit about both the structure and the tools and then that migration but that's where we're at right now. Once that's done, the next step then is of course to continue to iterate on the changes that we've made and improve them. One of the things that I'm really curious to figure out is like we made all of these changes based on feedback from the community. Now how can we start to measure whether or not those were the right changes? Like did we do this right? Did things get better or did we actually make it worse and continue to iterate and improve? That's a lot of things, right? Okay, so one of the things that we've done with the Drupal.org tools is part of that whole content strategy. Instead of just book pages that are kind of infinitely nested down into the tree, there are now two content types that we use for managing documentation. There's a documentation guide and then documentation pages. And the thinking here is that there's a real difference between structure which provides the navigation and the ability for things to be grouped together and the content itself. In the past, those were always basically the same, like our content and our structure was both the book pages. We now have guides, so you could say, for example, create a new guide that is the twig guide for Drupal 8. And within that guide, you could add any number of different documentation pages. They're all grouped together as sort of children of that guide page which gives us a lot of really cool new things that we can do. Like we'll see, for example, you could have a maintainer of a guide. You could say all of these pages in this guide are related. So when something happens to any one of these pages, it's kind of indicative of something in the guide changed versus what we've been able to do in the past is like, I know one page changed, but not necessarily how that relates to the rest of the content in this particular section. In the process of migrating everything from that into the new structure with the documentation guides and then pages within the guide, one of the things that we're trying to do is sort of flatten this sort of infinitely nested hierarchy. And I think this is gonna make, hopefully make it a bit easier for people to find things on Drupal.org and to navigate. I have a couple of examples here, all of what you've probably encountered in the past that I just think are sort of illustrative of why this is difficult for us right now. This one, for example, shows that in the top level of the develop for Drupal documentation, like one of the top level things is how to write simple tests for Drupal 6. But if you wanna learn how to, for example, implement a hook in Drupal 8, which is probably way more important initially when you're first learning how to do this than learning how to write a simple test, that's buried all the way under working with the Drupal API and then under Drupal 8 APIs and then under, there's one in here for like hooks, it's like four or five levels deep. And you get down that far and then you're like, wait a second, like at this level, here's all the documentation about how I do things when I'm writing code for Drupal, but this is all Drupal 7 documentation and the Drupal 8 stuff is actually nested one level deeper than the Drupal 7 stuff and it's just super confusing because it's inconsistent. So we analyzed all of the data about how people use Drupal's documentation and we basically figured out that like people who try to navigate two pages on Drupal.org via the book structure basically can never find the things that they're looking for because it's like you have this structure but there's no consistency to it. And it's hard to know like, is the information about testing under the developer guide, is it under the Drupal 8 APIs or is it in the, you know, module tutorial guides? It's just, it's super tough to find things. So the goal here is that the hierarchy and the navigation system should be flatter. It's instead of having a couple of really, really deep nested hierarchies, we should have a lot of really less deep. We should have more but have them be not nearly as deep. For the most part, we're trying to aim for, you know, a guide is only one level deep or maybe two but certainly not this, you know, nine levels deep of navigation. I think that this will help make it easier to find things on Drupal.org and I also think that it helps sort of promote discovery of things. It's easier for people trying to find content to go to one page and have a big long list of a lot of guides than it is to have to click in three or four levels deep into three different sections to figure out which of those three sections has the thing that you're looking for. I also think this is interesting. If anybody follows the Symphony Project and their documentation, they actually just did something really similar to this. Their documentation was basically completely rewritten and one of the things that they did was to separate it into a much wider and less deep structure for the same reason. You promote findability by allowing people to browse through it without having to necessarily browse many levels deep into a structure that they don't understand. So we're working on that. Another thing that's happening on Drupal.org right now is we're trying to split the documentation per major version. So like when you first go to the documentation page, it'll be like, would you like documentation for Drupal 7 or Drupal 8? And then you'll choose one and then you'll go there and then you'll know that the things that are in the Drupal 8 section actually relate to Drupal 8 and not Drupal 4 and it should hopefully help make it easier to find the things that you're looking for and make our documentation more consistent. This is definitely a work in progress. During the migration, a lot of what we've figured out is that there are just tons of these pages on Drupal.org where it was written originally for Drupal 7 or maybe Drupal 6 and then when Drupal 8 came out, instead of copying that page and creating a Drupal 8 version of the page, we tend to update the existing version and add sort of like, this is the Drupal 8 way of doing it and this is the Drupal 7 way of doing it and it's in the same page. What we're ending up finding is that as we're splitting the documentation, there's actually a lot of content that's missing for Drupal 8. Like it was written for Drupal 7 and we just sort of like, well, it's close enough so we don't have to worry about it and that's sort of part of this version split is the understanding that we are going to get into a situation now where, yeah, there's gonna be pages that are duplicate between Drupal 7 and Drupal 8 but they're different too. It's like they're maybe mostly the same but slightly different. So we're working on that. The idea then is that you'll have pages that are relevant to a major version of Drupal so we're doing a major version split. So it's like Drupal 7 or Drupal 8 but if you use Drupal 8 you'll know that there's Drupal 8.1 and 8.2 and 8.3 in the future. Minor version differences, we're still going to try to tackle those in line on the main Drupal 8 page. There'll also be ways of calling that out and trying to highlight it a little bit so you can say this particular feature was introduced in Drupal 8.3 just FYI. It's probably useful to know that if you're actually using 8.2. I also actually really like that having these kind of callouts in a page like that helps promote the readability of a page. It breaks these really long walls of text up and makes them easier to scan when you've got like blocks of code in the page then the syntax highlighting and stylizing things in different ways. I think it helps people read through that a little bit better which is kind of cool. We're adding the concept of section maintainers so we now have this structure and content and so the structure guide part of it, you can actually say this particular guide is maintained by Joe or by someone else. It's sort of a, well we don't need to get into the technical, how it works, rather the idea is that we recognize that one of the difficulties in Drupal's documentation is that whole lack of curation and subject matter experts reviewing the content and so we wanted to allow people to claim a section of the documentation and say, you know what, I'm really good at twig and I like helping out with documentation so I'm going to say that I would like to be the maintainer for the twig documentation and by doing so I'm able to help provide some review for other people that are reading, or sorry, writing the documentation, provide direction for them. It's that whole thing of allow people to click edit and make a change and feel confident in the fact that someone is going to review that change and make sure that it's accurate. By allowing people to be a maintainer of a section and assigning that to them on Drupal.org, we can also do a lot of other really neat things like for example, you can get an email when somebody edits one of the pages in your section so instead of having to go into the theming section on Drupal.org and follow every single theming page, you can say, no, I just want a notification whenever somebody edits or adds to the twig section, whatever that is now or in the future. That will help, for example, me to then remember, oh cool, Tatiana edited this page. I want to review the change that she made and make sure that it's accurate. Versus in the past it was like, it maybe got reviewed if I remembered that I wrote that page and then I went back there and checked it out at some point. There's also sort of a lot of outstanding questions about this section maintainers. The state that we're at with this right now is kind of, we built the tools to allow for this and now we have to figure out sort of like, what does it mean to be a section maintainer beyond the fact that you can get an email when somebody edits the content? What role do you play? I'm hopeful that as a section maintainer, people will do things like take the time to review the content that people are either adding or editing in their section. I hope that section maintainers will take the time to review the entirety of what is in their section and identify things that might be missing and need to be written. What we see a lot with documentation on Drupal.org right now is that it's like the page gets written because somebody had that problem and they came across the fact that the documentation didn't exist or more likely that they couldn't find it. So they added a page that documents that one specific thing that they were working on, but it's not necessarily covering everything within that topic. So as a section maintainer, I can say, you know what? In order to have a really complete guide about how to use twig, it should cover these five different things. And then finally, section maintainers should be able to answer questions that people have. Not necessarily like, I don't want this to turn into a support type of thing where you're like, oh, you're the twig section maintainer and I have this question about how to twig. Can you fix it for me? But it's more like questions like, I feel like this piece of content is missing. Do you think it belongs in this guide or not? Or this page seems to be inaccurate and I think that this is what it should say instead. Would you agree with that? And having someone else to talk to and discuss those things with, I think is gonna be a really cool feature. This also gives us the ability to do things like recognize the people that are taking the time and volunteering their time to maintain a section in ways that we've not been able to before. At this point, we basically have the ability to say, you're a section maintainer and now we can start to add things perhaps listing on your Drupal.org profile. Joe has volunteered his time to work on these different sections of documentation in the same way that we do with modules and various projects. Right now you can edit documentation and it's highlighted on your Drupal.org profile. There's one line near the top that'll say like, Joe has edited 500 pages and it's like, okay, great. What does that mean? Did he just fix typos? This allows me to say, I feel like I'm an expert in this subject and not only that, I'm willing to take the time to volunteer some of my own time to help maintain that and keep it up to date. So a potential employer in the future coming along might look at your profile and be like, wow, not only did he tell me that he knows about, what did I say I know about configuration management, he's actually been actively involved in keeping that documentation up to date. So I have a little more confidence in that knowledge. We've done a bit of work with the way that statuses are used on documentation pages. The concept of status has existed in the past and it would show up in a block over on the right-hand side. There were like 10 different statuses that you could choose from. I don't even remember what they all were. There was a bunch of them. It's been consolidated into a list, I believe there's three now, out of date, incomplete and deprecated. And the idea is that, and then we'll display that in a nice highlighted message right at the top of the page along with some additional instructions instead of just having a little thing over in the corner that says like, out of date and it's like red and flashing at you, you're like, what does that mean? They're all out of date. I don't trust any of these pages. We can now highlight at the top of the page, this documentation is marked as incomplete and we can prompt people and say, if you wanna help fix that, go here and help fix that, which is pretty cool. The default status for a page is also currently no status. And the theory then is if you come to a page on Drupal.org and it doesn't have one of these banners across the top, you should feel relatively confident that that page is up to date and accurate. We moved what used to be comments on pages in the documentation to a tab and we called them discuss instead. One of the things that we've seen with comments over the year, over the many years, is that people would come to a page on Drupal.org and the documentation would either be incomplete or inaccurate and instead of clicking edit and fixing the page, they would leave a comment with, oh, this part is wrong. Here's how it should be written instead. And the theory was eventually people would come along and they would do what's called a rollup. They'd read all the comments and they'd find the changes that needed to be made and they'd move them up into the documentation and then they'd unpublish or delete the comments. But that never really happened and so instead you'd end up with pages that have like a big blob of text at the top, none of which is right, but you think it should be right because it's the documentation and then like 100 comments and buried in one of those comments was the actual like this is the current working version of how this works. So instead we moved all the comments to a separate tab and we labeled it discuss. And the theory here is that we can use this now as a tool for people to say, hey, this page looks inaccurate, maybe it should be changed. Let's discuss what it should stay instead, actually make the edit to the page. Combine that with having section maintainers who are notified every time you leave a comment on a page and I think this will help to promote people's confidence in making changes to the documentation when they can do things like say, hey, I was thinking about marking this page as deprecated because I don't think that it's important and then someone else can come along and say actually this is really important. We still allow this so maybe we shouldn't deprecate the page and you can discuss it and I don't know. We'll see what happens, right? I like two days after this feature rolled out on Drupal.org, this comment got left where someone was like, wow, this is awesome. With the comments moved to a separate tab in the new system, I now dare editing the page itself. We're like, yes, that's what we wanted. And there's a ton of other stuff that got added too. You can follow a page or a whole guide and you can do that as an individual who's not a section maintainer. So even if you're not the maintainer but you just want to keep up to date, now I'm like, why would I want to follow? It's like I really want to know. I'm like stalking Tatiana. I want to know if she changed that page or not. But now it's so you can follow the pages and keep up to date and help review edits that people are making. There's now a WYSIWYG editor and syntax highlighting for all documentation pages. You have the ability to relate pages to one another so that you can say, you know, this documentation about how routing works is related to this other guide about menus because routing and menus, they're not the same but they're related. We're good, we will in the near future have per project guides. So every contributed module will have its own documentation section and can have its own maintainer for the documentation for that module, which is pretty cool. Rather than what we have now, it's like if you want to document your module, you either link to the readme or you go to some random place in the hierarchy and you add your page and then you link to it from your project page. And so now we can be a little bit more consistent about where that documentation is found. And there's probably lots of other cool stuff too. There definitely is. I like all of this because it helps to tackle a lot of the pain points that we've experienced. And I think that having covered all of those things, it's hopefully fairly obvious how we're attempting to at least tackle some of those pain points. This is in progress. Like right now, well not right now, but pretty much right now, this migration is happening and for a while while it's happening, when you go to Drupal.org and you go to the documentation, it's gonna be a kind of weird, like sometimes you'll end up on old style pages and sometimes you'll end up on new style pages as that migration from the old content type to the new content type happens. And then there's also, like we established all of these guides, but now we need to try to find and recruit people that maintain the guides. And so one of the things that is part of that migration process is migrating the content over, recruiting somebody to be a maintainer for the guide and then as a maintainer, immediately going and taking the time to say like yes, this is all the right content. It is in the right guide and they're in the right order and adding good summaries and that kind of stuff to the topic or the content within your section. So there's an issue on Drupal.org where you can go and sign up to be a maintainer for things that you're good at or are interested in. You can also come to the Sprint on Friday and we'll be working on migrating content. I would be more than happy to sit down and talk with anyone that's interested in being a maintainer about what that involves or how you could do that and be good at it or at least what I think would be good at it. But so that's a great opportunity to kind of get involved with this right now. The next thing I wanna talk about is the Drupal 8 user guide, which is another documentation project that's kind of in process right now. And for me, the user guide really boils down to this. The idea that if you really want your documentation to be awesome, someone needs to edit it. It needs to be reviewed and edited. Like nobody ever writes a book and then publishes the exact version that they just wrote. Somebody goes through and they edit it. Usually there are technical editors that review it for consistency and accuracy and all of that. It's quite a process. And the other thing that's tough is that it's pretty much impossible to successfully edit your own content. When you write something or when you read something that you wrote yourself, you already know what you meant to write. And so as you're reading it, it can be really difficult to just kind of get a sense of like, does this make sense? Are things in the right order? Did I use the right words? You also have a tendency to skim whether you're trying or not. You're gonna skim the content because you're like, I know what this sentence says. I just wrote it. So having someone else edit it, it's not just a like, you need to have someone edit because you're bad at grammar. It's like, you need to have someone edit it because it's impossible to edit your own content. So the user guide is a project where we're trying to create a guide that is limited in scope, sort of like a book that covers the learner to skilled transition that people may be making when evaluating and starting to use Drupal and to do some, wow, this thing. It's telling me, go to bed, Joe. Anyways, the idea with the user guide is that we'll write curated and edited documentation and we'll use it to replace some key portions of the Drupal.org handbook. It's trying to, it's a different approach to tackle a lot of the same problems that we are already addressing in different ways on Drupal.org, like curation and review, having things copy edited and so forth. I think what's interesting is this like, like unlike writing fiction where the sort of prevailing advice is like, just sit down and start writing and keep writing until you've gotten enough on the page and something will happen. When you're writing technical things or writing documentation, you really need to like sit down and make a plan for what it is that you're going to write. You need to say, we're going to cover all of these different things. This is in scope and this isn't in scope and we need to make sure that we cover these things. And so the idea with the user guide was we should write documentation where instead of just taking a bunch of random pages and putting them together, we should actually sit down and make a list first of all of the pages that we think we should write. And so a couple, it's a lie, almost two years ago now, a couple of us got together at a Drupal camp and sat in the corner for a weekend and basically made a big list of if you were to write the Drupal 8 user guide for people who are content authors and had some experience with Drupal, so they maybe knew some of the terminology but weren't necessarily experts, what would that guide contain? And we made a big list and then we set out to write all of the topics that we had identified in that list. We actually made a big list of all the topics and then we submitted that to a bunch of other people to review to say, does this make sense? Are we covering all the right things? And we got some feedback that said, no, you should maybe cover views in a different way or make sure you're covering this other thing. Anyway, so we started that process. Then we did some other things too. The user guide is actually written as ASCII doc, basically text files within a Git repository. It's a project on Drupal.org just like a module might be a project and that allowed us to have a little bit more control over the content that is in those text files than we would have on Drupal.org where it was just, especially at that time, it was anybody could come and edit your page and make any changes that they wanted to. This requires that only certain people have access to commit to the project. So if you wanna make a change to the user guide, you totally can but it's forced to go through an editorial review process before that change gets added. And another thing that we did is we took the time before we started writing any of the content to come up with really detailed templates for the content that we wanted to write so that we could get some consistency. And we basically said that when it comes to writing documentation, you're either writing, you're documenting a concept like what is a node or you're documenting a task like how to add a node. And so we came up with templates for both of those and every page in the user guide, whether it's documenting a concept or a task will follow that template and this helps with the consistency of the guide so people are reading through it and you know what to expect on every page you end up on. Versus the way things are in Drupal.org currently, it's sort of like we recommend a template but you have to be able to find it and know that it exists and there's no enforcement of that template. And so we were able to do a little bit of that. This is the slide that reminds me to go and show you the user guide because it doesn't fit in a slide. This is currently the in process demo site that we're using while we work on the user guide but just to give you a sense of how big it is and what all of this covers, we've got the whole table of contents here which is all of the things that we identified as we should probably have good documentation about each of these topics for Drupal 8. And then different, let's see, look at the installing a module one. This demonstrates sort of the template that we would use for a task page in the user guide. Everyone will start by listing a goal so you can say your goal, by the time you've finished reading this page you should be able to accomplish this thing. We'll walk through any prerequisite knowledge that you should have so if it's like and we're assuming that you already know what a block is and if you don't, here's the page where you can go find out what a block is and then step by step instructions including screenshots of how to do all of those things. Yeah. How close is it to being on Drupal? Very close. I actually have a slide for that. So the question was how close is this to being on Drupal.org? And the current status of this project is it's been written, the entire guide has been written in English, it's been copy edited, it's been reviewed. We've actually done user testing with it where we've had people that are like familiar with web tools but have never used Drupal, read the user guide and tell us like does this make sense or not and then gone back and made changes to it. So that's all been done and the current state is that there's work being done to import the ASCII doc text files as nodes on Drupal.org so that it can appear within the documentation section and that this is one of those like I had a slide for it and I didn't know what status to put on the slide because every time I would go to the issue on Drupal.org where Neil has been working on it, the status was like different. So I was like, well, I guess I'll just tell people it's really close but not quite done. One of the other things that's really cool about the user guide is the user guide has a defined scope. When we set out to write it, we made a list of everything that we would document and by doing so we were able to say we're gonna write these pages and nothing else and when we did that, we recognized that there is now a better opportunity to do things like translate the guide. It's easier to translate something that has a known end point than it is to translate the infinity of Drupal.org. It's also because of the way that it's implemented as text files in a Git repository, we're able to create some tools that make it easier for people to review and translate those text files. We can do things like add maintainers to the user guide project who have commit access for different languages. So we could say you're the maintainer of the Hungarian version of the guide. Because changes to the guide have to be made as issues in the user guide issue queue, we can also do things like say, we fixed this in the English version of the guide, now we need to port it to all of the, this would be the equivalent of you fixed it in Drupal 8, now you can backport it to Drupal 7. It's like we fixed it in English, now we can apply that fix and make sure it gets applied to all of the other language versions, which is pretty cool. This is also happening right now. We're sort of piloting the translation process with two different teams. There's a team working on Hungarian and a team working on Catalan. And the plan is to have them go through the process first so we can kind of iron out some of the kinks and get it all done and then open it up to a wider audience so anybody could translate it into the languages that they want to. We've done some really cool stuff too, like almost every page in the guide has multiple screenshots on it and we automated the tools that generate the screenshots. So when we translate it to Hungarian, we can install the Hungarian language pack for Drupal and then run the screenshot builder and it will take all of our screenshots in Hungarian instead of English and some cool stuff like that. So I kind of talked about this already, but the idea of making it consistent by creating templates and not only by creating a template, but also by creating a process that allows us to enforce adherence to those guidelines. Yeah. This is very reminiscent of with integrating this sort of setup with... Yeah, so the question is this is very similar to like a training or a curriculum style of documentation. Have we looked at integrating it with a learning management system? And we haven't at this point. That's interesting. I hadn't even thought about that part of it until you just mentioned it. Certainly the idea of like concept and tasks and having templates, like we did not make that up. We were like, how do other people do this? And then Didda was like, this is how all of the people do it. And we were like, all right, we'll do that. But yeah, it would be an interesting thing to look at that. I know that as a result of using some of these standards it's allowed us to work with some tools for translation that weren't previously available to us, which is kind of neat. So yeah, I'll have to look into that. Or if you have experience with LMS stuff, I'd... All right. Well, thanks for nothing. It just seems like... I'm not sure you would see it some sort of a certification. Yeah, yep. And yeah, it's like I mentioned at the beginning I create Drupal training for a living so that certainly that has influence on this. And a lot of the people that have helped out with it also work in places where they are doing Drupal training as a job. And that bleeds over for sure. It's actually gone both ways. It's kind of cool. I've learned a lot about writing good documentation by trying to help facilitate this guide. And I've been able to take a lot of the things that I've learned by being a Drupal instructor for DrupalizeMe and use that knowledge to say, you know, I've watched thousands of people try to learn Drupal and this is the place where they usually get stuck. We should make sure that we have good documentation on that. And then it goes the other way too where I go back to DrupalizeMe and I'm like, wow, you guys, we should really have like a template for our pages so they're consistent. So looking at this list again, the big difference here is that what we've accomplished with the user guide in addition to all of the same things that we accomplished on Drupal.org we've now made it possible to have translations of the documentation and we have a way of enforcing consistency, which is cool. I already told you about the current status but it's basically like somewhere close to done. So as a recap, I took a moment to kind of talk about how documentation is important because documentation is people's first impression of our software and ultimately it's important because if we want to grow the community and we want to empower more people to use Drupal, we need to be able to teach them how to use Drupal and documentation is how we do that. We talked about how the tools have changed on Drupal.org in order to allow us to write and manage documentation in better ways. We are now in a place where we have the tools and we need to develop policies and best practices for using those tools. The user guide is also in process and that project is turning out to be quite successful which is really exciting and we talked a little bit about that. And of course, in all of that, there are always things that we can do to kind of continue to make Drupal's documentation better. I feel like for me, one of the things that's happening now is I have to take a minute to kind of step back and reflect on this whole. We built a lot of tools and we can have maintainers. How do we recruit maintainers? And then once we recruit them, how do we educate them on like, you know, it would be really great if you applied this template to all of the pages in your page or in your section and encourage them to do so and build a sense of understanding about how that type of thing is important within our community and allow people to do that. So that's figuring that out is kind of the thing that is most interesting to me at the moment. There's also some things like for example, there's been some changes at the Drupal Association and going forward, it's going to be harder for them to support the creation of new tools like we've gotten over the last year because there's fewer staff to help create new tools and so there's gonna be a need to recruit people to actually help work on things like adding the ability to list the guides that you're a maintainer of on your profile, for example. Some of those things that aren't done yet but would be really nice to have. And I think we're also going to discover as we start to use these tools that there are some things that we wish we had done different and we're gonna need to figure out now how to make those changes but I hope that we can do so because I feel like I don't wanna see us end up in a position again where it's 10 years before we make changes to the way that these tools work and that we continue to iterate and improve on what we've been doing. So I'm like way over my time. So that's what I know. I was gonna say we could have a discussion about this. I totally love talking about this stuff. So either if you have questions now I'm happy to try to answer them or we can hang out in the hall. I'll be at the sprint on Friday and if you wanna help contribute to any of this please show up and I can help you find ways that you can contribute to this. And going forward probably the best places to find myself and other people that are working on this is on groups.drupal.org and the documentation group or on the documentation issue queue on drupal.org. Ta-da! I'm happy to answer questions until I get kicked out. So if you... One of the big pain points is...