 All right, I'm going to go ahead and get started. This session is about documentation for Drupal, both the product documentation that we create and we use to learn Drupal and understand how it works and the tools that we use in order to make that documentation available to create the documentation and so forth. And me, Joe and Tatiana are going to co-present. Both of us have some things to share about documentation and what's going on in the world of documentation with Drupal at the moment. So that's us. Yay. What we're going to talk about in this session are these following things in roughly this order. We're going to talk a little bit about what documentation is. So the various parts of Drupal and Drupal.org and things in our community that we consider to be under the purview of documentation and why documentation is important and why we create it and what our goal is when we're creating that documentation. And then we're going to talk about the current state of things. I've given similar presentations in the past and I try to, at least once a year, sort of say over the last year, this is what we've accomplished with documentation. These are the pain points that we're feeling currently, how we're trying to address them. And then also using this session as an opportunity to hear from others in the community about where they might be feeling pain points and how we can continue to improve this stuff. Normally, it kind of ends there and it's like a real downer and I'm like, yeah, documentation, we need it and it's not that great. But this time around, it's really awesome because in the last year, year and a half, we've made a lot of really awesome improvements to Drupal.org and API.Drupal.org and the processes that we use for creating Drupal's documentation. Tatiana's going to talk a lot about those things and what we've accomplished in the last year and also what you can expect to see in the coming year. And then at the end, we kind of based on the things that we're going to talk about, we've got questions about various processes and the changes that we're making and kind of things that we're looking for input from the community on to help us improve how those work. And we're hoping that we've got enough time at the end that we can ask you guys some of those questions and get feedback in your thoughts. So first off, what is documentation? I would say that these are the things that the Drupal community would consider to be under the purview of documentation. Anytime you hear somebody say Drupal documentation, they're probably talking about one of these things which is actually quite a lot of different things. There's the community documentation on Drupal.org. So if you go to Drupal.org and you click on the documentation tab in the top right navigation and you end up on any of those handbook pages, that's kind of a wiki of sorts, that's all community generated documentation written by people in the Drupal community, including all of us in this room. We've got the documentation on api.drupal.org which is the documentation of Drupal's code base. This is documentation that's parsed from comments in the Drupal core code and it's displayed as an API reference for developers. The primary purpose of this documentation is being able to look up, for example, a function or method reference and understand the use case and when and where to use it. We've got a new project that's been being worked on for the last year or so, the Drupal 8 user guide which I'll talk more about. It's an attempt to create a bit more of a curated, edited handbook or guide for beginners to get started with Drupal 8. And then we've got all of this other documentation that kind of exists outside of the Drupal.org system but it's like blog posts that people in the community write, videos that companies produce or even in people that spread out across YouTube and various company blogs and sites. And I would consider a lot of that to be documentation in a sense because for those of us that are trying to learn how to do something new in Drupal, we often go to Google first and we search like how do I do thing X in Drupal and a lot of times the answer comes up on some site that's not Drupal.org and that's still valid documentation. So all of those things, when we talk about documentation and sort of why we create this and the purpose, I like to look at this pyramid that represents personas that were developed for Drupal.org to try to better understand the people that make use of Drupal.org. And usually when we talk about documentation, we're trying to write materials or produce materials that help people who we would put in the learner category here and to help them advance further up this pyramid from learner to skilled to expert and master. The newcomer part historically on Drupal.org is a little bit more covered by stuff that's kind of a mix between like marketing and documentation. It's a little bit of like, you know, what is Drupal 8 is often a combination of like Drupal 8 that's shiny and fancy and you should use it to build your business and synergy and stuff and then there's also, and Drupal 8 has fields and entities and so there's a weird hybrid there. But for the most part, we talk about documentation as a tool that helps move people along this pyramid and improve their skill level as Drupal developers which also means it's a tool that helps us improve and increase the size of our community by adding new people and helping those people move along this pyramid and become more skilled Drupal users and developers. Hey. So, state of documentation and things that are kind of going on at a really high level right now. For the last, probably couple of years really, the primary focus has been on improving Drupal 8's documentation and the tools that we use to document Drupal. Of course, a lot of Drupal 7 documentation improves as a result but our focus has been on Drupal 8, you know what, it's been out for about six months now, so leading up to that, there was a lot of effort put into making sure that we had quality documentation for when it was released and now continuing to improve that documentation. The majority of the effort that I've seen in the community of recent has been towards creating new pages in the handbook that help document aspects of Drupal 8. I feel like I have to be quieter now that the door is closed. And improving the Drupal 7 documentation. We've also recently seen tons of Drupal 8 blog posts and videos and content that's being produced by all kinds of people who are now starting to use Drupal 8. Leading up to the release, it was kind of documentation was being written by the people that were writing the code for Drupal Core and they'd documented as they went and now we're in a state where six months later, a lot of people are starting to adopt Drupal 8 as end users or for client projects and such. And so the documentation that's a little bit more facing the site builder or site administrator is seeing a lot of work and improvement right now as those people are starting to make use of Drupal 8. And in that process, these are some of the things that we've pain points in the process that we've been feeling or where we feel like we could improve both the documentation and the tools that we use to create that documentation. One of the big ones that we've been talking about for a while is just sort of a lack of curation overall. You can see this a lot with like Drupal 8 documentation coming out and there's a theme guide on Drupal.org and it covers some topics of theming but not all of them because it really only happens to cover whatever the person that was needing the documentation at the time and couldn't find it decided they would write down but there's a lack of people coming in and saying, you know, the perfect outline for a theming guide would be this and we should make sure that we cover all of these specific topics. So we don't have a lot of that type of curation. We're also with the ability for anyone to come along and edit pages on Drupal.org which is awesome because anyone in this room could help improve the documentation. We don't have great review, tools for review. So I might have come along and written a page that contained information that was mostly correct and then Chris maybe came along and edited that page and added some information that was also mostly correct and then Tatiana came along and edited the page and just changed it all to something that was not right at all. But unfortunately, I as the person that initially created it and maybe the subject matter expert didn't know that that happened unless I remembered to go back and check that page every couple of weeks I wouldn't know that someone had edited it. Those edits don't get reviewed and that's a bit of a pain point. Versioning, you can see this with the Drupal 7, Drupal 8 problem. It's like half of Drupal 8's documentation lives on a page where the top half is Drupal 8 and the bottom half is Drupal 7 and then somewhere mixed among it is like and every other version of Drupal. And then sometimes there's the Drupal 8 blocks page and the Drupal 7 blocks page and the Drupal 6 blocks page. And being able to separate documentation and the version of Drupal that represents. The organization of things kind of related to that you just get this endless hierarchy in the handbook on Drupal.org where you're drilling down, drilling down and then all of a sudden you're like you've jumped from one guide in the handbook to another one completely because somebody linked you to the blocks documentation and the developer guide and it can be a little bit confusing. Translation is something that we hear a lot for non-English speaking communities the documentation on Drupal.org is all in English and there are not tools on Drupal.org to translate it. I don't know that we are ever going to be adding tools like that but we can look to adding tools that will make it easier for some of these communities to maintain their own copies of the documentation. We see some of that now like there's like Drupal.es where there's a bunch of Spanish documentation where effectively people have copy and pasted pages from Drupal.org and then translated them which is awesome except those pages never get updated and so they don't necessarily match the documentation that's accurate on Drupal.org or maybe inaccurate depending on who edited it last but that's a bit of a pain point and then finally this last one which is I totally recognize not something we can do anything about directly but except for a talk about it really loud every time we get the chance which is there's an issue when you write blog posts or create videos or do any kind of documentation about Drupal and post it on your own site it's like unless you put a date on it or add some kind of this is the version of Drupal that this documentation was written for it can be really confusing for people that stumble across it and this is especially true right now where a lot of the things that people find initially for Drupal 8 were written like a year or two ago and they show up in the top of search results because they've been around for a long time and they've been linked to a lot but in some cases they're just completely wrong because Drupal 8 changed a lot since that documentation was written and as a newcomer that's really frustrating to like load read some documentation and then go to Drupal 8 and it's like click on this link to build a view and I'm like that link doesn't exist why is this lying to me? So encouraging people to either keep their pages that documentation up to date or to post some kind of notice on the page that's like hey we recognize this is out of date things have changed. Excuse me. So that's kind of a bit of what's going on right now and a bit of the pain points that we're feeling but what we're going to do here then is kind of walk through each of these different pieces of documentation api.drupal.org the community documentation in the handbook and the Drupal 8 user guide talk a little bit about each of those projects what we're trying to solve with them and the progress that we are or are not making on those cases. So first up api.drupal.org which interestingly enough I don't really have much to complain about with this one I usually complain a lot about documentation can be better here and fix these things api.drupal.org is working really well and it has been for a while. So at the moment we're not making tons of big changes we're just kind of trying to keep it running and make sure that it continues to serve the community well. I also want to make sure that as we talk about these things we say thanks and give praise to the people who have helped make sure that the documentation is awesome api.drupal.org is pretty much entirely kept up by Jennifer Hodgden and Neil Drum these two do like 99% of the work of making sure that that site works and that when you need to figure out how some function in Drupal works you can go there and find it. And then the documentation itself is written by everyone that contributes to Drupal core. So we gotta say thank you to all the developers for taking the time to make sure that they write comments for the code that they're writing and hopefully making sure that they write accurate comments and then update them when they change the code which in most cases they do. So that's awesome and thanks to all of them. In the last year or so there are a bunch of changes that have been made to api.drupal.org to help it continue to function well. We've added an improved landing page so when you first get to api.drupal.org the page that you see that for any of the Drupal 8 reference guides now contains a list of links that is a little bit more curated. We tried to organize things by listing them in the order that you're likely to need to understand or encounter them. So it's like what is Drupal is listed first instead of I think in the Drupal 7.1 it's like understanding entities is the first thing and then the last thing on the list is oh by the way you should know what a hook is too and it's like well this is not a great order and so we've helped try to curate the order of those things a bit. api.drupal.org has syntax highlighting now which is pretty cool. It makes the code that you're looking at a lot easier to read. There's been changes to the code that make it so that the system works with the new semantic versioning for Drupal 8 so there's now when you go there's a tab for 8.2 and 8.1 and 8.0 and that's good because it makes it easy to just switch between all of those and make sure that you're looking at the documentation for the version of Drupal that you're using. I attempted to add a bullet point for this last one which is not here yet but we've also added or not we but Jennifer and Neil added the ability for api.drupal.org's documentation to be indexed by solar on the Drupal.org infrastructure so now when you perform a search on Drupal.org in the big search box right at the top results from api.drupal.org will be returned within those results which is pretty sweet. So really for the most part we're doing a pretty good job with the API documentation and mostly it's just saying thanks to the people that make that work and continuing to do so. So then community documentation which I said is all of the stuff on Drupal.org that it lives under the documentation tab on the main page there so community documentation you might often hear people refer to this as the handbook. Over the last year there's been a lot of people making changes and contributing to that documentation. It's basically an open wiki so as long as you have an account on Drupal.org you can click the edit tab on almost any of these nodes and contribute changes and help improve the documentation or add new pages. In the last year we've had 790 some people who have made two or more edits or added pages on Drupal.org which is pretty impressive. That's a lot of people that are helping out and there's this really long tail too. It's like there's another 700 some people who made one edit on Drupal.org. The graph here kind of represents the distribution of people like amount of edits that people have made which you then kind of see too there's a handful of people that do a vast majority of the documentation and a lot of people that contribute one or two things here and there. Both of which are really valuable and both of which we would like to encourage and continue to support. So we try to make sure that any changes we make to Drupal.org will allow for both of those scenarios. And again some people that if you encounter or you run into you should say thanks because these guys help to make sure that the documentation on Drupal.org is accurate and up to date and continue to make it easy for the rest of us to understand how Drupal works. So I know I like these slides. I find it really awesome to be able to have the opportunity to celebrate the people that contribute to documentation. Our community I feel like does a really great job of saying so and so had this many things committed to core for Drupal 8 and that's great but there's a lot of work that goes on outside of writing code and documentation is one of those things. So that's my bit about the community documentation. Tatiana's gonna share a little bit about the changes that are kind of in the pipeline for Drupal.org and how we're going to help tackle some of the pain points that I pointed out earlier over the next year or so. Or sooner? Maybe so. I hope this wasn't over the next year. I didn't want to like promise this will be done tomorrow, right? Well, in two weeks? Three weeks? And yeah, my team is sitting here on the first row like looking at me with evil eyes. Yeah, I will speak a little bit about what we, when I say we, I represent the staff at the Drupal Association engineering team who are working on various changes for Drupal.org. So that's what I mean by we in this context. So to give you some background, why are we even working on documentation instead of like people like Joe? Last year, we had a project and we developed overall content strategy for the website. We had various recommendations ready for new content types and for better ways to structure content on the website. And if you follow one of those two links, you can find more information about that. We had various sessions at previous Drupal cons in Barcelona, Los Angeles, with all the details about overall content strategy for the whole of Drupal.org. And so this year and the last maybe half a year, we are focusing on implementing that stuff. Obviously, the website is big and we can't just do it all at the same time. So we're taking part of the website at the time and we are focusing on it and we're working on it. The first few things we've done already, the About section, the Drupal 8 landing page section, which I hope you saw, it came out together with the Drupal 8 release and the About Drupal.org section. So those were the first things where we tried out some of the ideas and now our primary focus is documentation for the last three months, maybe four months, something like that. And so that's where we come in and trying to fix all the things Joe was just talking about. So for documentation specifically, for documentation section, here are some of the things we were trying to do some of the goals we had. Obviously, the overall goal is to improve quality of documentation, but some of the more specific things and changes we wanted to introduce through changing tools were we wanted to introduce the concept of maintainers for parts of documentation. So instead of the whole community maintains the whole documentation, it will be more like sort of what we have with projects. There is a project, there are a few people who maintain it and there are people who can contribute by suggesting changes or uploading patches, et cetera. So something similar, maybe less strict, still more open for everyone to edit, but still want to have some maintainership and some people who commit to taking care of this particular bit of documentation. We wanted to flatten way too deep hierarchy. Sometimes you probably saw in the handbook like the sidebar can be longer than the content, like three times longer and you can go deep like six levels and then completely be lost. So we wanted to have that fixed and make it more flat and more understandable for people. Another very big problem is how do we split documentation perversion? Again, George has talked about that. Notifications for people, just to let them know, here's, I came and I broke your page. You should know about that, right? And then a big question of how to make comments more useful. There are different opinions, some people really like comments, some people really, really hate comments, but they are not ideal right now, I would say. So we are making some changes there. So a bit of our process. Again, as I said, we started, I think in January, but last year we knew that we will be working on documentation sometime soon. So what we've done in the autumn back in September, we actually launched the survey. You maybe saw it, it might have annoyed you a little bit. There was like a box in the bottom right on the documentation pages and then we would ask you a few questions about what sort of information is helpful about this page, how you can evaluate it, it's up to date, et cetera. So we collected that information and also about the same time, we introduced some Google Analytics events in various places on documentation pages so we could collect the data to see what people click, do they use sidebar, do they use navigation at the bottom, et cetera. So by the time we are ready to start working, we had that data to make some decisions. So that was something we done last year and then we started by creating a story map. Essentially we wrote a bunch of user stories based on our user research and based on sort of exercise we had with the documentation working group. We essentially tried to cover all the different things, different types of users do when they touch documentation tools and that screenshot which you can't really see is like a pile of post-it notes which we used to create the thing. So then we could prioritize and pick what are the most important user stories we need to start addressing first. Based on that, we created a set of wireframes to wireframe our ideas how the new system could work and look and then, yeah, that's an example of the wireframe on the right. So then we actually run a couple of usability testing sessions in person and also remotely on those wireframes with real users who were looking and telling us if they were completely confused not completely confused. And then incorporated that feedback, obviously. We've done revision to wireframes. We created the actual designs which will look more like here's actual thing and how it will look. And then we did usability testing again. This time in person at Drupal camp, sorry, London, we actually set with people and make them click and tell us what's happening. Again, we got some very useful feedback. Some of our ideas turned out to be not so great and we came up with new ideas. And so incorporated again all the feedback and starts building the thing. So right now we are at the very last stages of this build step. So I would be really happy to show you things but they're not exactly ready yet but should be soon. So it's coming. So what is the thing we're building anyway? Essentially, we are creating two new content types to replace book page content type. And the difference is the first content type is documentation guide which will be essentially a container content type which will group documentation on specific topic. And this guide will have maintainer dedicated to it and it will enable things like notifications, et cetera. And then the second content type is documentation page which will live inside of the guides and that's where the documentation will actually be the actual words. We live there. So here is the documentation guide to mock up. So that's not the real thing yet. That's a design. That's how we wanted to look and work. So, yes. So this is purely a container for documentation content. So the only text which is actually part of this content type is that short description at the top and I recognize you can't really see it well but well. So, yeah. The guide will have a description of contents and then below it you can see the list of all the contents of all the pages inside of it. This list is like automatically generated. You don't need to care about it. It will just work, right? So on the right side, you can see things like navigation, docs, maintainers, et cetera. So this is an example of a guide which has maintainers, hooray. There will be a lot of guides which probably don't have a maintainers or not at the start. So there will be an ability to mark a guide with different statuses such as seeking co-maintenors if you need help or the guide needs maintainers if there are none and then instead of maintainers we'll display messages which tell people how they can step up and help. And so the idea is that overall permissions will be the same as in most users on the website who are not spammers can edit any documentation page but then maintainers of the guide will have additional permissions and additional things they can do. Behind the scenes, the guide is actually an organic group and so if you are a maintainer you will be able to do some administrative tasks on admin group page. So things like manage all content in the group, modify the menu and other users as co-maintenors or editors, et cetera. So here is an example of administrative content page. It will be much longer obviously so here you as a maintainer you will be able to see all of the pages inside of your guide. You will be able to sort them, filter them and perform maybe bulk operations, et cetera. This is the example of the modify menu UI so that menu you saw on the right side you will be able on this page to actually move pages up and down and it will be much easier because you can just drag and drop them and the current system, the book outline means you have to go to each page, click outline, pick a new location for this page, save. You have to select from a select list that's like 15,000 items. This is where I would. So we hope people will like it. And yeah, this is the example of UI to add other people as maintainers or editors. Right now we only plan to have a maintainer role for guides but maybe in the future there will be need to have two different roles a maintainer or editor. Maybe we will want to have different permissions. I don't know, that's what people will want. People like Joel tell us to do, we'll do it. So this is a mock-up of the documentation page itself. So this is what will replace the current book pages and these pages will leave inside of those guides I just showed you. Well, first of all, you might notice we removed a lot of clutter and sort of information which people were hoping will be helpful and they kept adding it and adding it and then it became too much and it wasn't helpful anymore. So we sort of removed all of that and just left really helpful things. So at the very bottom, very prominent you can see breadcrumbs in our usability test and we actually found that breadcrumbs are really, really helpful for people to even understand where they are on this page, where this page is located on the website. So we made them much more prominent than they are now. Page title is fairly short because this is a mock-up and we can do whatever we want to buy. We also are actually planning to introduce actual restrictions on the field so you can't create crazy long page titles which are not helpful. That will happen. Last updated date is pretty prominent. Again, that's a survey we've done, the very first step. One of the things we found out from that was that last updated date is like the main and only metadata people look to evaluate the page and see is it up to date, is it relevant for them? So we removed all other things and we just kept the last updated date and then you can see that updated is a link. It links to the last revision of the page so you can see, well, it is last updated but was it actually meaningful update? Maybe someone was cleaning up spam or fixed a typo and the actual page is still out of date. So just an easier way for people to get there and check what happened. On the right side, you can see menu. So that's the guide menu. All the pages inside of the guide, this current page is in and you can see the current page sort of as active there. That's the menu which maintainers can modify through the UI, I just showed you. Another interesting thing is that big green button which is called edit. So we removed all of the tabs which had like five options of different things because really the only thing we want people to do on this page is edit it to make it better. So we just showed them a huge green button edit and then other things are hidden behind the drop-down. So in case you wanna do something else, you can still find it, but really you should just edit the page. You will notice that in the menu, the hierarchy is actually flat. That's what we were talking about. So even if you wanna add like five child pages and then child of child and child you can't. So there is one level of hierarchy and that's it. And the idea is if you feel like you need more child pages, you will have to create a guide which will live inside of this guide. And the idea is that you will only create a guide if you have like big enough topic, if it's not like one page, but it's a topic which is self-contained so you actually need a guide and maybe you will ask some other person to be maintainer of it. If you just wanna add a tiny page, you should maybe work it out in this flat menu and not create anything else. Again, those are our ideas. We actually are very curious to see how it will work because people tend to do things we don't think about. So that will be interesting, but so far at least in the usability test and that worked really nice and people were really happy to see those changes. Some of the bright things in the main content area are call outs. So just additional things to be able to highlight important information and they will be available through CK editor. So you'll have actual visibility editor maybe someday on documentation pages and there will be a button like add a template and you can select different types of call outs depending on what sort of information you want to highlight for people. And yeah, you can't really see it but the copyright statement is there for people who really like copyright statements. It's at the bottom, so you can't see it. Promise you. Yes. It came out, so let's see. I think I told you most of the things. So another thing I wanted to talk about is statuses. We did some changes to the current book page statuses. Well, first of all, we found them not really useful. That's what people told us in usability testing and surveys and so we cut them down from 10 statuses to like three as a first step. So we removed, first of all, the no known problem status because that's like a default. You can see it on almost every page and it doesn't tell you anything. Like, does it mean there are unknown problems somewhere? So right now in our new system, essentially default is no status. If there's no status, if you don't know if there's any problem, it's just, it looks like there is nothing. And then if there is some problem, we left you three statuses to pick from, out of date, incomplete and deprecated. And for those three statuses, we don't actually just display status. It also doesn't tell you much. Instead, depending on the status, we show your custom message on top of the page, which gives you a little bit more information and also tells you how you can improve it and fix it if there's a problem. So that's an example for out of date status message. The other interesting question is per version split. So we had a lot of brainstorming on this topic. Everyone has different opinions. The plan we have right now is sort of twofold. First, to split documentation per major version, so like seven versus eight. This will be done in the IA itself. So you can see in the breadcrumbs in every page, it starts with like Drupal eight or Drupal seven, if you're on Drupal seven page. So the idea is there will be top-level guide for Drupal eight documentation and then top-level guide for Drupal seven and all of the guides will be inside of those. So when you create a page, either put it here or you put it there and you don't mix them, hopefully. We'll see. And then, so that's for major versions. And then for minor versions, the idea is that the split will happen in the page itself. So example you can see on the right, that's sort of a callout for specific nodes for eight.3 version because something changed or whatever. So again, we hope that the main body of documentation will always be about the latest or be applicable for latest version of Drupal. And then if there's something which you need to highlight or which used to work but isn't working now, then you can use this type of callout which will clearly tell you for eight.3 or for eight, that whatever, here is information for you. And so all the minor versions will live on the same page and we will see what happens when we get to eight.20. Maybe we'll change our mind, but not soon. So what about comments? This is a wireframe, it will look better. But the question of comments, so the way we decided to tackle it was we are moving them to discuss stuff. So first of all, they won't be at the bottom of the page, they will be at the separate page. And the idea is that that's the place where you would go to suggest changes to the page or discuss something about the page, sort of very similar to what other wiki-like projects have. And I know one of the ideas which was floating around for a while was like, let's have an issue for every single page or documentation where we will discuss the page and then we'll use entity reference to connect the tool. And that's a lot of issues. And now we can have, because we have notifications and we can actually let people know that discussion is happening, we can have it right on the page so we don't have this like separate place connected to the page. So comment to discuss stuff, you will be able to suggest your improvement at top. You can change status if you wanna say, oh, this page is actually out of date and I don't really know how to fix it but maybe someone knows, I'm just telling you that it is out of date and it's not applicable anymore, that sort of thing. So you can change the status right there. What we also do, we automatically generate a comment for every edit, sort of similar to issues. So you can see, this is a wireframe of edit tab. So at the very bottom, you can see the same field status and explain new changes. As you edit the page, especially if it's not a typo but like substantial edit, you can explain what you've done right there and whatever you enter in that explain new changes field will go on discuss tab. So then discuss tab will always be the full history of the page, all suggestions, all whatever people changed and we'll even display if you change something like a field, a title or status, we'll display it right in your comment again, sort of similar to issues. So again, you can go to discuss tab and see everything what was happening for this page and this is a screenshot from development environment so it will look better. It's sort of getting closer, but yeah. But it's working already, so that's nice. So additionally to all of the things I just talked about, a few things we are thinking to add which might come a little bit later. So the things I just talked about is our sort of MVP, the word people hate. That's what we wanna push out the first and then with time we want to add some other changes such as following an email notification for pages and guides. So for pages actually, that's already there. You can follow the current pages and you will be able to follow the individual pages for documentation. What we wanna do is let people follow the guide and so then you will receive notifications for new pages inside of the guide, for all the edits, for all the pages, for comments. Obviously, we'll make it so you can select what you wanna receive if you don't wanna receive all the things. Real Visivik editor is on the list as well as syntax highlighting. So again, syntax highlighting is already there right now on the pages, but Visivik is not yet so we're working on a CK editor and it should come soon, hopefully. Related content is another thing so we're going to add a field where you can add whatever content is related to this page so it can be another documentation page from a different guide or maybe from a different version if it's relevant or maybe it's a blog post or something else. Again, that's sort of next step. Official guides for projects. So we want to be able to connect a project to a guide and you saw on some of the mockups before in the sidebar we actually had a list of projects. So the idea is the field will exist on the project page and as a project maintainer you will be able to say this guide is official for my project so I connected via entity reference and then connection will be displayed both on documentation and on the project page itself. Yes, and obviously displaying guides on user profiles so some of the things we are thinking about how to say thank you better. First one would be just if you are maintainer of the guide same as right now you can see all the projects person maintains you will be able to see all the guides person maintains. Hopefully that will encourage people to maintain guides. It's funny because that was like initially was my number one complaint. I was like I want to be able to give credit to people that are maintaining sections of documentation. So then it took spiraled out of control and all of a sudden it's like wow we need like maintainers and organic groups and then we need to move the comments and it was like really we just wanted to be able to say like thanks for editing things. Now we will build this whole thing just to say thanks. No, that's not true. We'll build it for other reasons. Yeah, so those are a few things which are already done. They are small but still nice. So the big elephant in the room for this whole thing is migration. So once we are done and all of those beautiful tools exist we need to take all of the documentation and move it over here which will be big. So the way we approach it, at first we wanna try and recruit maintainers for parts of the documentation. So if you have something you really like in documentation come and tell us. Like I really wanna maintain site building guide for something or whatever is that. So we wanna have a list of people to start with and then we're hoping they will help us to create the initial structure of guides and sub guides and then we are building the migration tool which will be essentially you click a button I wanna migrate this page into this new guide. It tells you are you sure? You say yes and then it migrates. So behind the scenes it will switch the content type of notes so we won't lose the history. We won't lose the existing comments or anything. It will change the content time and it will put it into this new group and it will remove it from book outline. And after a while we probably won't have book pages at all hopefully. And yeah, success in the end when that happens. Joe will talk a bit about user guide. I think too that it's worth pointing out that a lot of these, the reasoning behind these changes is based on research that we've done like Tatiana pointed out but also just like a year plus of us spending a lot of time thinking about and talking to people how would you like to edit documentation and what could we do to help improve those things. And if you're curious about all of that history there are sessions from the last two Drupal cons in which we kind of, you could probably start in LA and watch it progress all the way to here and hopefully next time there'll be even more. Yeah, I can say words. So right now we have that related content field I was talking about. Right now we're only planning it for content which exists on the site, not external content. So if you want something external you can put it in the bottom of the page right now. Like you can link to a video. We are not planning to have any special tools to connect external content just yet. This might be a good idea, we might add it later if it makes sense. Okay, we'll go on the list. Wait, now you can follow. So I'm gonna talk a little bit about the Drupal 8 user guide project which is another attempt at solving some of these same problems and from a different way and also trying to make sure that we have some really awesome documentation for people who are just getting started with Drupal 8. This project started about a year ago as an attempt to create some a bit more curated documentation for Drupal 8 that basically boils down to a handful of us got together and thought you know what would be really awesome is if we wrote an outline of what the ideal documentation for someone as a beginning user of Drupal 8 looked like and then we actually wrote all of the pages in that outline. Versus what we end up with a lot on Drupal.org is someone creates the initial like top level page and then people kind of come in and fill in things here and there but you're often missing big gaps. Like it might explain users and roles but it never explains permissions or it might explain entities but not fields and so it's just sort of we wanted to make sure that we covered everything. And we've spent a bunch of time working on this over the last year. Again, first of all I wanted to say thanks to all of the people that have helped contribute to this over the last year. There's been a ton of people that have gotten involved in the user guide project that helped to write the documentation, helped to, we've actually done the documentation that we're writing for the user guide has been going through a copy editing phase. We've had users test the documentation so there's been a lot of people involved with this which is really awesome again. So thanks all of you people. So a bit more about the user guide. The idea again was curated documentation and the benefit of that curation is that we make sure we're covering everything instead of potentially having gaps in the documentation. It started out with writing this outline that we identified our target audience. We said okay the target audience for this is someone who already knows what Drupal is. They've already chosen that they wanna use it on their site but they've not built sites with Drupal before so this is probably the first or close to the first time that they've made use of Drupal 8. And we're going to help them get from that learner they've just kind of started using Drupal 8 to a skilled user. They understand all of the core tools and how to make use of them, the terminology and so forth. So we wrote an outline to that persona saying if you were this person what would you wanna know? And we tried to use that as a way to make sure that we covered the right things but also to make sure that we didn't cover too much because the other thing you often end up with on pages on Drupal.org is that they very quickly go from like explaining what an entity is to like explaining the complex annotation system for how you add an entity in Drupal 8 and it's like wow that's appropriate for some people but not everybody. And then we also wanted to be able to create version dependent documentation so we could write a Drupal 8 user guide and then when Drupal 9 comes out in the future we could effectively create a fork or a branch of the documentation that is the Drupal 9 version and keep that up to date. And then the idea being that pages in the user guide will be used to kind of replace key portions of the community documentation handbook with this more curated documentation. This is a little bit we're still kind of figuring out some of the parts like how are we going to do that? How are we gonna deprecate some of the stuff on Drupal.org and replace it with things that are in the user guide and so forth but it's a work in progress. This is everything with Drupal. The user guide project is it currently lives at Drupal.org slash project slash user guide. It's a, technically it's a Git repository full of text files. The text files are written in ASCII doc which is a Markdown-esque syntax for writing, marking up content in a text file. It's really commonly used in technical manuals. I know that O'Reilly Publishing uses ASCII doc for writing all of their books. Ultimately, we had a really long conversation about the different ways that we could format these text files and ASCII doc at the end of the day was the winner at that time. We knew that we wanted it to be text files so that ultimately we could put it in version control because version control provided us with a lot of tools for doing things like peer review of changes to the documentation that we were struggling to do on Drupal.org as it currently exists. So for example, with Git, you can make a pull request or submit a patch to a piece of documentation with your proposed changes but someone else can review those changes to make sure they're accurate before they end up in front of the general public. I think kind of that at the moment. I think I have my slides out of order. We'll look at this one. Here's an example of some of the pages, what the pages from the user guide look like right now. The one on the left, yeah, the one on the left, this one. There's an example page from the user guide. One of the things that we tried to do was create a template for every page or topic. We actually broke it down. We said some types of things that you wanna learn are concepts and some things that you wanna learn are how to perform a specific task. So we have task templates and concept templates and depending on the type of thing that you're writing about, you follow that template. So you'll know that every concept page you end up on will be formatted the same way and contain like basically read with the same flow. We also started adding attribution to all of the pages. So whenever somebody helped by writing or copy editing a page in the user manual, we were able to provide attribution in this attributes.txt file. It's kind of an equivalent or our attempt to do something like issue credits where when you write code and you submit a patch and you help fix an issue with Drupal Core, for example, you can get credit for that as can in any organization that you would like to list as helping you achieve that. We wanted a way to make sure that we could list people that had helped with documentation and attribute the work that they were doing. And also to make sure that we can kind of do it with substantive edits. One of the things you see with Drupal.org, it's like you can see that I edited a lot of pages, but I might have just fixed a bunch of typos. I might not have contributed useful documentation. It was just like, well, I added a period here and fixed a link there and like, well, that's helpful. It's creditable in a different way than the person who actually wrote the entire page. And so we wanted to be able to address some of that. The current status of this project is as of last week, actually, we've written all of the 99 pages that we identified in the outline for the documentation. So the last one was completed last week. And we're currently taking one of two passes at copy editing this documentation. The first pass we're going through and trying to be consistent with the way that we do things like make sure that whenever we say Drupal Core, we say Drupal Core, not just Core, that we say email, not e-mail, kind of editing for consistency. There's a lot of weird terminology in Drupal that people often get confused with, like upgrade versus update. And we wanted to make sure that whenever we use words like that, we're consistent with the way that we use it. We wanted to make sure that when you describe a task, like navigate to this page in the navigation that is written in using the same format every single time so that when somebody sees it, they're like, oh, that's telling me to navigate to something in the administrative toolbar. So right now we're kind of going through making sure that it adheres to all of those guidelines. Once that's done, the next copy editing phase is we're actually gonna have a single person go through and edit the entire guide for voice to make it read as if it was written by a single person and consistent voice instead of what you end up with on drupal.org right now. It's like, depending on the page you're on, they all read a bit differently and who wrote it. So we're in that copy editing phase for consistency of use and guidelines right now people are actively working on it. It's definitely something we could use help with if people are interested. So it'd be a really awesome task to help out with at the sprints on Friday because it's essentially it boils down to get a copy of the guideline, find an issue, make sure that drupal is capitalized wherever it's used and then search through the guide and make sure it works and it's relatively easy to get way to get started with this. And then finally, we've actually been doing user testing with the guide too. The written version of it we've been giving to a couple of different people who have been going through the entire guide and trying to do what the guide told them to do and provide us with feedback about whether or not it made sense and things that we should change which has been actually a really positive experience because it's helped us identify things that we thought were really important. Like we thought it was gonna be really important that we talk about Drush whenever you could maybe use Drush. So if you're gonna enable a module we should tell them how to do it in the UI and with Drush. And most of the people that were in this testing persona were like, I don't actually care about this Drush thing. It's just really confusing. And we're like, okay, well we'll put it in appendix for now and see how that goes. But making progress. However, there's a lot of stuff with this that we still need to figure out. The slide didn't get finished? No. No, okay. That's all right, we can make it up when we go. What I've learned about documentation is you just need to talk with authority and people will be like, oh yeah, he knows what he's talking about. But so both with the user guide and with the changes that we're making on Drupal.org there's lots of stuff that we still have questions about and we're trying to figure out. I think the user guide as an example is it's different and it's a new way of writing the documentation and now it all exists in these text files and we have to figure out like, well how is that going to exist on Drupal.org and how is it going to show up in the search index and so forth, figuring out those things. We need to figure out problems like the user guide duplicates content that's in pages in the handbook on Drupal.org and how do we handle that scenario because we don't wanna end up with duplication but we also don't wanna be like, hey Chris, thanks for all the work that you've done on these pages in the handbook. We're gonna delete them and kind of make sure that we handle that in a nice manner. So that's a quest, one of the things we're trying to figure out. We're also gonna, with this whole Tatiana was saying, we're gonna move all of Drupal.org to this idea of guides that need maintainers. Turns out we have to find people that are actually going to help maintain those guides and how are we going to recruit people to do that and just kind of in general, like how do we continue to improve our tools to produce higher quality documentation. And basically kind of wanting to open up this discussion and see if you guys have ideas about this. If you, originally we thought, what we're gonna do is we're gonna invite everybody to the presentation and then before it ends, we're gonna lock the door and we're not gonna let anybody out until they commit to maintaining one section of documentation. That's still the plan. Oh, that's still the plan? Yeah, it's like here. But really, we're just curious to hear feedback from you guys about these proposed changes, ideas about how we can continue to improve these tools and so forth. Yeah, so questions or feedback or. Does this work? Yeah. Sounds like it. Okay, I'm not gonna do what you just asked me to do. I'm gonna ask a completely different question. That's fine. There is a vast amount of what I think of as documentation that's available on the web. You work for a company that provides some of it. Sean on Drupalize Me. Chris Shattuck has a build a module thing and there's a lot more as well. Lynda.com does it and everything else. It is how I learned to use Drupal. I'm seven or eight years into it. I still rely on it as a crutch. And I'm just kind of curious how you see the documentation system you're all working on here interacting with, using, supplementing, replacing, all the stuff that people are actually earning a living, teaching people how to use Drupal. Sure. I mean, I can speak to that from my perspective on it anyways, it's gonna be different for everyone. And I am totally one of those people that earns a living by creating documentation for Drupal. As someone that's in that environment day to day, I totally recognize that for most people, Drupal.org is their first source that they go to if they have a question about how something with Drupal works. Like I actually work for a company whose main goal is we'd like people to end up on our site instead of Drupal.org and it's really hard to make that happen. And because Drupal.org has such good search ranking and so forth. So my hope is that by creating these tools we help to improve the quality of the documentation there, for sure. I don't think we'll ever supplant things like Drupalize Me and build a module and people who are writing blog posts for their site that explain how to do things in documentation because for various different reasons, those are great attempts for people to create marketing on their own site, it's a way for us to make money by creating videos that teach people Drupal. My hope then is that Drupal.org can continue to be a canonical source for answering questions about how certain things work in Drupal and really I hope that it can answer questions to a certain depth. I don't necessarily know how deep that is but it's like to me you should be able to get answers to basic questions about Drupal on Drupal.org for sure and to a certain level of learning. If you looked at the pyramid with the personas I definitely think Drupal.org should be able to handle the learned to skilled and probably skilled to expert for the most part. But it's also unrealistic to expect Drupal.org to document every single possible thing in use case that we could hope to accomplish with Drupal and so you'll continue to see Drupalize Me and build a module and everybody writing blog posts and that kind of thing. Does that answer your question? No? No. Yeah, okay, I totally. We go in the same guide as a different sub page and it concerns the philosophy of what documentation is intended to accomplish and making sure that we're being specific about that because it's somebody who's made some community edits. I really often find myself being like I either disagree with that or I disagree that it should be in the documentation but I don't feel confident removing it because there's not a clear statement of what this is and isn't and the specific use case I had in mind is there's a lot of places in like some of the cyclotor guides where the answer will be if you wanna do this use this in Drupal and especially in the Drupal 7 world where you can't do a whole lot without using a fair amount of contrib that's probably appropriate as we get into a world where core is a lot stronger. I felt that some people kind of use that section to advertise their module and their module is kind of crap. So how do we avoid that? Because it creates confusion when you say I wanna do this use case. Here's 14 different modules that might or might not do it. Right? So I think there's a couple of questions there or like things that we could talk about. One of them is the element of not necessarily feeling confident in your when you make a change to a page whether that was the right change to make. And I think that we're hoping that some of the changes we're making specifically to the way that comments work will help alleviate some of that. Right now what we see is that a lot of times people are not confident enough to click the edit button and make a change but they do actually know the answer so they'll leave a comment but then the comment never really makes it back into the documentation. We'd really like to try to encourage people to more frequently click the edit button and make their changes. That's why it's big and green. Yeah, that's why it's really big and green. It's friendlier that way, right? And that we also hope that by allowing people to understand that there is a review process and that the changes that they make will be looked at and reviewed by others that help alleviate some of that imposter syndrome because at least you're like, I think this is right but I know that Joe who is the maintainer of this section will see that I made the change and review it and help make sure it is right if it's not. We see this a lot with the way that developing code for Drupal Core works where people are able to post a proposed change and the community is able to come and review that change and see if it makes sense and contribute to it and make it better. And that encourages people who might not know how to answer the entire question to at least start the conversation of answering it. So hopefully that's what happens with some of these changes for the comments stuff. The other part about what happens when I wrote some sweet module that was better than your not-so-sweet module and so I went and edited the page and provided links to it. I think that's a much harder thing for us to answer and a little bit will, in my mind, it boils down to or it helps to have maintainers of a section who are considered to be, if we can get to a point where we consider maintainers to have decision-making power about content within a section of the documentation, we allow for an easier way to resolve some of those conflicts whereas right now it gets resolved by, well, you just go edit the page again and add your link and then I'm like, no, no, no. And I edit it and add my link. If we can hopefully provide ways to have like mediation around that. Yeah, I feel like the power to make decisions is really right but we also need to guide people what are the right decisions. So your question is really governance one and this means we will have to work out policies and get some consensus on what is okay and what is not and what sort of module is okay and not and that feel for related projects we already had those questions about it so that's definitely something we'll have to talk about and before we even put it live we need to be able to tell people here's what you can put and here's what you can't put there and here's why. So then maintainers could make decisions based on something not just like whatever they decide. And also I feel like they're about to kick us out. So maybe we should like have a buff tomorrow something to talk more about this. Yeah, and I'm happy to like stand out in the hallway and then chat for a minute too. Yeah, so I think Joe and I will try to schedule a buff for tomorrow to just talk about this stuff. We'll tweet about it and yeah, come and talk to us maybe.