 So I'm like, hey guys, this will be good. So I'm going to talk a little bit about the state of documentation for Drupal, Drupal.org, the code and or the documentation that is part of Drupal core, kind of everything documentation related, some of the things that the community is working on in order to attempt to improve the documentation. And then I'm going to solicit your guys's feedback and help on some of that stuff. My name is, whoa, hold on. There we go. My name is Joe, or EOJTheBrave on Drupal.org, Twitter, IRC, pretty much everything since forever. I am a member of the Documentation Working Group. The Documentation Working Group is a handful of people from the community that were chosen to help oversee sort of policies and such around Drupal documentation, policies and guidelines to help resolve any disputes that come up and that kind of thing. So I'm a member of that group and as such I know a lot about the things that we talk about in that group. I mentioned this too because I'm going to talk about a lot of those things, but I also need to point out that in some cases, this is my impression of how things are going and how they should work and is not necessarily reflective of the entire group. And this presentation has a whole bunch of links in it. So if you feel like clicking on links or if you're watching the video and you'd like to follow along at home, you can go to this URL and there's a bunch of slides. So I kind of mentioned this already but what I'm going to talk about is the current state of documentation. So what is the documentation that we have? What's good about it? What's not so good about it? Then I'm going to talk about some of the work that we're doing on Drupal.org and in other places to improve that documentation and a little bit about why we're making those changes. And then finally I'm going to talk a bit about this new project, the Drupal 8 user guide, which is something that started around the time of DrupalCon in Los Angeles where I actually gave a presentation similar to this one, which I said here's the state of documentation, one of the things we could do to improve it is write a user guide and now we've started writing it and I'm going to talk a little bit about how that's going and how far we've come and so forth. I think one of the first things to think about with this is like when we talk about documentation for Drupal, what is it that we're talking about? And the thing is, it's like our documentation exists in a lot of different places. And so these are just some of them. The ones that people generally go to first or when you think about documentation for Drupal are either the handbook. So if you go to Drupal.org and you click on documentation tab up at the top, you end up in the community handbook which is basically this giant wiki, I think it's something like 12,000 pages at this point of community contributed documentation. And then there's api.drupal.org which is the documentation that documents Drupal Core's code and all of the internal API. So as a developer, you probably make use of that documentation a lot when it comes to doing something like looking up how the format date function works. That documentation also has comments. So similar to, for example, php.net's documentation, you'll get information about a function and what it does and how it's supposed to be used. And then you'll also have some comments where people will sometimes provide helpful information like examples of how you can use it and sometimes provide unhelpful information like examples of how you can use it. There are also change records on Drupal.org which in a sense I think are a form of documentation. And what they serve to document is whenever there's a significant change made between the way that something in, for example, Drupal 7 works and how it now works in Drupal 8, not always, but for the most part, change records get filed for those things. So for example, if there was a function in Drupal 7 that was removed and there's now a new version of that or a new way of performing that thing in Drupal 8, there'll be a change record that documents that. And there's usually code samples. So one of them will say like, this is how you implemented this hook in Drupal 7. This is how you do the equivalent in Drupal 8. So those are change records. And then there's also this Drupal 8 user guide which is a new project that the Drupal community is working on to create a bit more of a curated guide for beginners, people that are new to Drupal and kind of want to get an understanding of what the site building experience is like. And then there's all this documentation that exists in our community that isn't really part of the Drupal communities purview, if you will. It's things that exist on external sites. I worked for a company, Drupalize Me, that creates training videos. And in a sense, those are documentation about how Drupal works. There's tons of books and blog posts and videos and that all over, typically found by searching in Google. But that's documentation as well. That element of documentation isn't something that the documentation working group really has any control over. I don't get to say, hey, sorry, can you not write that blog post? But that exists as well. And a lot of it is really awesome. So I'll start out by talking about some of the things that are really great about our documentation. And I do this because I think that when we talk about what's not awesome about our documentation and the changes that we would like to make, I think it's important to remember what's going really well for us. So that we don't lose those things as we make changes. I think that api.drupal.org and the documentation that we've got there is really good. It could certainly be improved, but for the most part, the documentation is good. It's generally easy to follow and it's generally pretty complete. And I like that. And there's a few reasons that I think that api.drupal.org documentation really stands out when we look at all of our documentation sources. The biggest one for me is that documentation tends to be somewhat curated and it's definitely required. Anytime you write code for Drupal Core, which is where all of the api.drupal.org documentation comes from, if you implement a new function or a new system in Drupal, you're also required to write the documentation for it as part of the coding standards review. So that patch that you wrote won't even get in unless the documentation is written, which is kind of cool because it means the documentation gets written. I also think the change records are really great, especially as we're making this transition from one version of Drupal to another, I think for those of us that have been working with Drupal 7 for a while, these change records are gonna be super helpful because I know how to do a lot of things in Drupal 7 and I know that I can still do those things in Drupal 8, but I don't necessarily know how and I think the change records will help with that. I think our community does a pretty good job of this concept of drive-by editing. The handbook on Drupal.org is all wiki pages and so if you have an account on Drupal.org, you can click the edit button and make changes and so we get a lot of people that come by and fix typos in the documentation and that's super useful. It helps improve the documentation and that's something that I think that we should continue to support in some way or another is the ability for people to contribute to documentation without having to jump through a lot of hoops to do so. And I also think that we're, as a community, we're getting better and better all the time at celebrating the people that work on documentation and recognizing them for that hard work and there's a lot of people that contribute to documentation. These are statistics from basically since the beginning of the year, since January 1st. We've had just over 6,000 total edits to handbook pages on Drupal.org, which is awesome. So 6,000 times someone has come by and said, you know what, we can improve this documentation and done so. And these are the people that have helped contribute to that. So 6,000 edits, roughly 1,000 people have contributed but what's interesting about this is that when you start to look at the numbers, while there's 1,000 people that have contributed, there's really like 20 people that have contributed the vast majority of the changes. If you've ever seen graphs of like what Drupal core contribution looks like, you've seen this graph, right? It's like five people wrote Drupal core and then a whole bunch of people helped with it. The documentation kind of tends to be the same. There's, so on the left, the really tall part is number, it starts with, from the left, you've got number of people, so we'll say one, or sorry, 300 some people have made one edit. And if you come across this way, it's how many edits they've made. So you can see there's a lot of people that have made like one or two or three changes, but then never come back and make any more. This is only since the beginning of the year, so this isn't all time statistics, but I think it's probably reflective of the, like what, you would see a similar long tail like this if you looked at statistics since forever. And that's awesome that we've got this many people contributing, but I think one of the things that we could look at is what would happen if we got everyone that was making only one change to make two instead? So now instead of 6,000, we'd have 12,000 changes. And that's huge in terms of improving the documentation and getting people to contribute. So I'll talk a little bit more about that later in the presentation. The other thing I wanted to point out, now that kind of switching into like, okay, so those are the things that are awesome about documentation. Now let's talk about why we have documentation and what we can do to make the things that aren't so awesome a little bit better. This pyramid of skills is part of a project that developed personas for Drupal.org. The idea was to identify groups of people, the types of things that they might be using Drupal.org to do, and the ways that they participate in the community. And then over time, we'd like to use Drupal.org and all of the tools that we create to help transition people from the bottom of this pyramid up to the top of it. So basically someone that's new and has never used Drupal or heard of it before, how do we funnel them into becoming masters of Drupal over time? And the documentation that we write and all of the tools that we create to allow people to write that documentation are part of that process of moving people along this trajectory from being a newcomer all the way up to a master. One of the things that's fascinating about this is, I think it's probably safe to say that with these personas, every single person that's attending DrupalCon this week is in like halfway of, I would say, about where the word skilled is and up. Like just being in the skilled category is like, oh, you're like just by virtue of the fact that you know what Drupal is when you're attending a community event, you're already in that like top 30%. So this is a huge group of people that we can help get moved into those higher groups, but also like there's a lot of potential there for us to tap into those resources and help get them editing the documentation as well. So as we talk about making changes to our tools, we often do so by taking a look at these personas and saying, if we make this change, let's say we make it so that change the tool that someone uses to edit documentation, which of these personas does it affect and how does it affect them? And if it does, are we using it as a way to help transition them from say skilled to expert? All right, so that's all the stuff that was awesome. This is some of the things that the documentation working group and the community over time have identified as pain points in our documentation and things that we'd like to see improved. This is primarily relates to the documentation that is part of the handbook. So the big wiki section on Drupal.org, though I think it applies to most things. So in no particular order, lack of curation and review is something that comes up a lot as being a pain point for the documentation that we write. Anybody can go to a page on Drupal.org and edit it and make changes and fix a typo or add a code example or whatever the case is. And there's no formal process for those changes to be reviewed. The way that they do get reviewed is somebody else happens to notice that there was a change made and come along and look at it or update it or fix it. But there aren't great tools for, so for example, Boris does a lot of work on the theming documentation. And there's no good way for him to know if I've come and made a change to something that he wrote, so that he can go, oh yeah, that is correct. Thanks for making the change versus, that's not a good way to do it. Maybe we should consider improving the documentation. The organization and the hierarchy of documentation is insane at this point. You go to the handbook on Drupal.org and it becomes this nested tree that just kind of goes down into the right forever. You're like, holy cow, that's a lot of pages. It's not necessarily a bad thing that there's all of that content, but we definitely struggle to keep it organized. I think a lot of this stems from the fact that in the Wiki system, anyone can come along and they can create a new page and they can create that new page anywhere in the Wiki. So there's not a lot of, we end up with a lot of pages that are kind of like, well, is this really the right spot for it? Or did you know that you've duplicated a page that exists in another section of the documentation? Which you probably didn't, because you went down this tree, but it was actually in that other tree. So thinking about and working on ways to deal with that, I think, are important. For me, that partially comes back to this idea of review and oversight and somebody that's more familiar with the documentation might say, hey, did you know that that existed already? Maybe you could help us improve that project or that page rather than writing a completely new one. The discoverability of documentation is a bit challenging. It gets better and better all of the time as we improve these tools, but it's definitely something where, I've talked to a lot of people who, when you ask them like, where did you learn that information? They're like, oh, it's on duple.org slash node slash one, two, seven, nine, five. And you're like, you mean you remembered the node ID of the page that documented the thing? So it's either that or people finding it through Google, it's often brought up as a pain point for people that we talk to about how they use the documentation is that it can be challenging to find the things that they're wanting to read about. Probably stems partially from this fact that there's just a hard to keep organized hierarchy. Versioning is another problem. You go to all these pages on duple.org and it's awesome. It's like, this is the page for how to do this one thing in duple six, seven and eight. And you're like, okay. And then they're all kind of different. So I'm not positive that this is gonna cover all of them. And you start reading through it and it's like half the paragraphs are like, this applies to duple seven, but not duple eight. And you get through and then you're like, this applies to duple six, but not duple seven. That can be really tough as someone that's learning how to do something new. Because why should I need to differentiate between versions of duple? I'm like, I'm building a duple eight website. I don't really care how duple six or seven did this same thing. But the way that our documentation is set up currently, there isn't really a great way to version resources in the documentation and say, here's the duple seven version of this page. Here's the duple eight version of this page. You know, the equivalent of that would be, if your documentation was all in a version control system, you could write all the documentation for duple seven. And then when duple eight development started, you could just create a new branch and say, here's the duple eight documentation. A lot of projects do this or similar. And you often see this in that, you'll go and view their documentation and they'll have like a little toggle at the top that's kind of like switch between versions of our software's documentation. API.duple.org does this really well because it's parsing the code and getting the documentation from there. That code's obviously versioned. And then translation is tough. Translation of documentation is tough because there are 12,000 some pages figuring out which one should be translated. It would be difficult. There's also an issue of if I created a page and then you translated it and then I changed the page. Now your translation's out of date but you have no way of knowing that I changed the page and you need to update the translation. What we see mostly with translation now is that people, different language communities will create their own Drupal websites and translate a select number of pages from Drupal.org. They'll just kind of pick the ones that they think are important and start translating those. They very quickly become out of date but it is a useful resource. So with that in mind, these are some of the things that the documentation working group has identified as sort of priorities for things that we can improve in order to help solve some of those pain points. About a year and a half ago or so, we, the group, when we was first formed, we went through a process of basically reading like all of the issues in the documentation issue queue and identifying themes within those issues and trying to group them together to say, what we hear the community saying over and over is for example, they would like the ability to follow or subscribe to a page in documentation. The idea being that if you've made a change to a page or it's a page that you're particularly interested say you're the maintainer of the flag module, you could follow the page that documents the flag module so when somebody makes a change to it, you would be notified and then you could go and review those changes. Another idea was introducing the concept of maintainers for documentation, whether it's for a section or a page. We have this concept of maintainers for Drupal projects so themes and modules and as a maintainer of a project you gain a little bit more authority over that project. You get to, well with projects for example, only maintainers can commit code to it but you also gain some additional karma I suppose as being the maintainer of a project and so if we could allow people to identify themselves as maintainers of say the theming guide on Drupal.org we could do things like give them additional tools and permissions to do their job well, like for example, get updates for all of the pages in that section but we can also then recognize those people better. We could do things like on your Drupal.org profile we could list the sections of documentation that you've said I'm maintaining in the same way that we do with projects and when people come and view your profile that's a nice way for them to get a sense of like, hey, this person is doing some good work in the community. And then creating a better link between projects and the documentation for those projects. So for example, the flag module and the pages on Drupal.org that document the flag module so that as a maintainer of the flag module I know what pages are out there that exist that document it but also as someone is trying to learn more about it, how that module works it's easy to find the documentation for it. And then the Drupal.at user guide is our kind of another priority right now which is this project of which I mentioned earlier to create a sort of comprehensive introduction to site building with Drupal. So with that in mind some of the things that we're doing in order to resolve some of those pain points. The first one is changes that are being made to Drupal.org and all the tools and the infrastructure there in order to support documentation. There's actually some really cool and exciting stuff coming up in the not too distant future. For this work, in this case a lot of the work and the way that things get changed on Drupal.org is the Drupal Association employs people that work on Drupal.org and make those changes. And the community and the documentation working group are asked to play an advisory role. So we get to come and say hey, these are things that we've identified as being important and we'd like to get solved and then let's work together to get that worked on. This also ties in with a lot of the content strategy work that's been happening on Drupal.org recently and just overall plans and changes for Drupal.org. But hopefully what this is gonna look like is Drupal.org is going to switch to a new format in which sections of documentation are created as essentially organic groups. So you could have an organic group or we'll just say we'll have a section or a group that is the theming documentation. Pages that are part of theming would then be inserted into that group. This creates a little bit more hierarchy and structure to the documentation but it also allows us to deal with a lot of the things that we just pointed out that are pain points. Like for example, you could say that someone could be a maintainer of the theming guide by virtue of the fact that they're an owner of a group and you could have multiple maintainers. This would modules, the organic group suite of modules and already has a lot of tools in place for helping deal with things like notifications, for example. So getting notification when somebody posts a new page into your group, you could take that to getting notification when somebody creates a new page in the theming documentation so that you can then later come back and review that page. So that's a big one, just that idea of maintainership and the idea that tools like organic groups allow us to provide a little bit more structure like an information architecture behind the Wiki that allows for us to group things together in a way that you can realistically subscribe to a page or a set of pages in the documentation and get notice. I'm hopeful that even just the getting notice part will help us make that transition from people that come and only ever make one edit to people making two edits because what happens now is like you go and you edit a page because you happen to discover it via Google search and then you probably never come back to that page ever in your life. If we could let you edit the page and then say I'd also like to be notified when somebody makes changes to this page. Next time somebody else comes along and makes a change you could get a notice and then you could say I'm gonna go review that change and make sure that the page still makes sense. Another thing that we've been talking about a lot is the comments on Wiki pages on Drupal.org are varying degrees of useful. They range all the way from actually useful to not useful at all. And how do we make that better and what do we do with them? What ends up happening a lot of times is people leave so you go to a page in the Wiki and you leave a comment on that page and usually most of the time those comments are either questions where you're asking for clarification in the documentation or they are the clarification themselves. So they're improvements to that documentation which I really wish you would actually just edit the page and put the improvement in there but it doesn't always happen, unfortunately. Sometimes it does happen and now you've got a comment that says it would be really great if the documentation was updated to say this and it does say that and now as the person that read the comment I'm like what is going on here? I don't get this. And then when somebody asks the question in a comment on the documentation that says this part isn't clear it would be way better if rather than leaving a comment that says oh well what you really need to do is X as if the documentation got updated so that the next person that read it that was clear as well. So we talk about using comments as more akin to how Wikipedia uses comments where there's like the talk or discussion tab on a page and rather than treating the comments as part of the documentation itself which we kind of do now, we would use the comments as a way to discuss the documentation and suggest improvements. So it's a combination of comments but also if you could imagine every page in the documentation having its own thread in the issue queue where people could discuss that piece of documentation and the status and whether it needs updates and so forth if we could use comments like that I think that would be amazing. There's a lot more information on Drupal.org about the changes that are happening to Drupal.org meta. As well as Tatiana did a session earlier this week on the content strategy and the work that's being done there which is definitely worth checking out. Okay, so that's the changes on Drupal.org and kind of where we're hoping to go with that. At DrupalConLA I gave a presentation similar to this one in which I talked about what things that are pain points in documentation and we had a long discussion afterwards and one of the things that we talked about was I had done a bunch of research into how other open source projects write their documentation and how that compares to what we're doing. Specifically I did some looking at WordPress and the Mozilla Developer Network. And I like these examples because in both cases they have over time transitioned from a community wiki much like Drupal.org to a more structured version controlled system for documenting. WordPress is actually still in the process of that. So like half of their documentation is actually version controlled and edited and reviewed and all of that and half of it is still the community wiki. MDN on the other hand is completely in version control and they end up with really high quality documentation. The downside is it's actually really hard to contribute to the MDN documentation. There's like an entire book that you have to read just to be able to like fix a typo. Which is kind of annoying. Then we talked about it a lot. The session went long and we talked about it like basically through the entire lunch period and then at the end we decided we should pursue this idea of writing a curated manual or guide for Drupal 8. This is something that the documentation working group had been talking about for a while and this was our opportunity to kind of get feedback from the community and at that point a lot of people expressed like yeah this seems like a really great idea. So the idea was to write curated documentation that would replace some key portions but not all of the documentation on Drupal.org. We identified that one good place to start would be with sort of a site building user guide. People's first, a lot of people's first introduction to Drupal is through the documentation on Drupal.org. So if we were able to provide this really awesome experience with the first set of documentation that people read, hopefully we can get more people loving Drupal and involved in our community. And we decided to do this by creating a new project, much like you would a module and writing the documentation as a book of sorts. But instead of just an individual writing the book we're trying to write it with the whole community. We initially were going to we put together a whole proposal for what this book might look like and how it would get written and we thought about ways that we could seek grant funding in order to employ someone to like basically pay someone to write the book. But then we got so much interest from the community in helping out that we decided well we'll give this a try and see if we can write this together as a community which in the end probably ends up being a better thing because ideally something like this becomes maintained by the community and not by an individual. So if we create processes that allow us to write it as a community, hopefully better. The guide is currently it's being written in a format, a text format called ASCII doc. It's kind of, it's like Markdown or Textile or any of those text formats that are ultimately parsed into HTML or some other format. It's divided up into a whole bunch of different sections and then tasks and concepts within that. One of the things that we did was we had a core group of people sit down and identify what would an awesome outline for a user guide for Drupal look like. This helped deal with some of that organizational hierarchy problem where instead of having like anyone can add a page anywhere we actually sat down and wrote an outline and said this is exactly what this book is gonna contain and this is the order that it's going to contain those things and hopefully it makes it easier to read through and for people to follow. It's all being written in text, text files that are version controlled with Git and this has a lot of benefits because it means much like code that's submitted to core or any project we have the ability to have content that people write for the guide be reviewed before it gets added to the guide. And all of the reviews and updates happen in an issue queue which means we've got a great place to discuss the work that's being done. And it's going okay, we're making progress. We've divided this up into three phases. We decided let's have an initial writing phase where we try to just like get something on the page and write each of these sections and then we're gonna come back and do two passes at editing it. One of them will be a pass where we basically confirm that the instructions that were written actually work. So like read the guide and follow the steps that were outlined in the guide and then there'll be a phase where someone goes through and probably just one or two people go through and edit the entire manual for voice so that it sounds and reads as if it's all written by an individual rather than what we end up with right now is there's quite a bit of disparity between the way that different people write and it can be really jarring when you go from one page to the next and it just sounds like it's a completely different person that's written, well it is a completely different person and it sounds like it, it makes it hard to follow. We've been tracking progress, we've got this spreadsheet that we use as a way to, we've identified what each of the things are in that in the outline we've written a few notes about what this section should cover and then we've been working with people who are interested in writing sections to say, what are you interested in, what do you wanna write about? Once you've found a section, we'll assign that to you and then we've got various different statuses and but I pulled this up because I was just looking at it the other day and at this point we're looking at roughly about 40% of the outline that we identified at DrupalCon LA has been, has had someone take an initial pass at writing the content for it. There are more of them that have someone has claimed that they're going to but in a lot of cases what happens is someone says, yeah I'm gonna write it and then we never hear from them again. We have some policies like for example, we say we'll give you two weeks and if we haven't heard from you in two weeks we're gonna unassign it and we'll let somebody else choose that task and that's been working pretty well. We've got a lot of really good guidelines and templates in place so we have a whole section on if you're writing about such and such in the Drupal user interface and you wanna identify a string in the interface this is the formatting that we use for identifying strings. If you're gonna take a screenshot this is how we take screenshots and this is how we annotate our screenshots so that if we need to update them in the future it's easy to do so. Having this content be in version control and having those types of templates and guidelines will hopefully make it easier for the content to ultimately be translated as well. Once the text is all written and we've edited it for voice just like with Drupal Core and the user interface strings for example once we say this is what the copy's gonna be we have the ability to allow people that are interested to translate it and be pretty assured that it's not going to just change out from under them at any moment. That's also part of why we have these guidelines for how to deal with images and such is that we'll need to be able to take screenshots of the Drupal interface in different languages when we translate the guide to different languages. But it's coming along well. This is an example of a page from the guide right now. Kind of things that are neat about it and I think are gonna be really helpful. We've got templates for what each page should look like and the information that it should contain. We've identified that generally there are two types of things that we're documenting we're either documenting a concept which is like what is a region or what is a theme or what is an entity or we're documenting a task that's like how do I add a region to my theme or how do I create a new node type. So we've got templates for if you're writing documentation about a concept what that should look like and if you're writing documentation about a task what that should look like. We've also created a hypothetical story that the documentation will tell so that the whole guide will be written as if it's you're building you're all working towards the same end result rather than what you end up with right now as you've got all these different pages on Drupal.org then there's really no cohesive thread through the documentation which can make it hard to follow. So our story is these sort of guiding principles that's really rough it's basically we're building a website for a farmer's market and we're using that as a way to identify sort of certain components within it like when we talk about creating content types there are content types that we can relate back to this idea that we're building a farmer's market website when we talk about creating roles and who the users of our site are gonna be we can relate those back as well and it helps create a mental model for anybody that's reading it that they can reference. And there's been a lot of people that have helped out with it which is super, super exciting and mostly I just wanted to say thanks for everyone that's been helping with the documentation in creating this user guide and that's been great. One of the things that this is kind of a side effect of this user guide and the process that we had to go through in order to write this text and have it be on Drupal.org it has to comply with Drupal's licensing and in order to do that it has to be Creative Commons license and in order to be Creative Commons license you have to write attributions for everybody that contributed anything to the documentation which is both a pain in the butt and really awesome because we can do things like this where we say so and so John McDonald contributed to writing the concepts and regions in the theme section as did Michelle, I'm gonna butcher this and she works at Erd Fish similar to the way that we've worked on tools that allow code contributions to Drupal to be attributed to users so individuals and or organizations we can start to do that with documentation as well which I hope will compel people to be more active and contribute. We got a lot of work to do though to finish this up. We're making progress. The nice thing about the guide in compared to the other changes that we talked about but the changes to Drupal.org are primarily going to be the work of the Drupal Association. There are times where there is an opportunity for people in the community to help out but usually the actual bulk of the work the heavy lifting is done by people that work at the Drupal Association because they have the ability to make those changes. Yeah, but you can totally come to the sprints. We're gonna talk about that in a second, see? But things like the guide are a little bit especially if you are new to Drupal are a little bit easier to help get started with so anyone can help. As a process of writing this one of the things that we've discovered is that and this is kind of true of documentation in general though writing documentation is a task that seems to be really conducive to sprints or user group meetings or that kind of stuff. When we've worked on the guide we'll get these like surges of activity where we'll have a sprint and a whole bunch of people will help participate and a whole bunch of people will assign themselves a task and work on it for a while and then it tapers off afterwards and then if it's been a month or two since we've had a more focused sprint there's not a lot of activity. I suppose probably similar for Drupal core projects the same thing happens when there's a sprint there's a lot of additional activity. One of the things that I've noticed though is that because we're using the issue queue to write this documentation as somebody comes to a sprint and they start contributing to a topic and we assign that topic to them and now next week I can just go leave a comment on that topic that's like, hey, how's this coming along? And the person's like, oh, that's right I was helping out with the documentation and they actually come back and help finish it rather than like what happens with documentation sprints now a lot of times as people show up and we work on editing wiki pages on Drupal.org and it's great and they maybe make some progress and then they just disappear but there's no easy way for me to just kind of give them a friendly push in a week or two and be like, hey, remember that thing you said you were gonna help with? It'd be great if you finished it and if you don't, that's okay. So that's a benefit of this and I think that I think we'll also see as a benefit of, for example, the transition of using things like comments to discuss the documentation rather than as part of the documentation is that if you could follow a page in the documentation and be notified when someone left a new comment it's a similar effect. Like, hey, it looks like you did a lot of work on this. Did you know that this system changed? It would be great if the documentation was updated or whatever the case is. So one of the big challenges that we have left with this is obviously writing it all but then there's also the aspect of once it's written how does that content become part of the Drupal.org system? How does somebody, it's again, it's basically the discoverability. Once the guide is written how does somebody get to it and find it? There's some ideas about how to do that and we've been working on it but I think that'll be one of the trickier bits of it to solve. If you wanna help out with any of these projects and are gonna be at the sprints on Friday there's a couple of ways that you can contribute. We'll have a table where we'll be working on just documentation in general and the user guide. I will be there along with a couple other members of the documentation working group. We've got tons of different issues that we could work on kind of depending on what anyone is interested in. There is like Neil mentioned if you wanna help out with changes to the infrastructure and sort of makeup of Drupal.org related to what was talked about at the beginning of the presentation with switching to groups and using comments in different ways and all of that type of work. Seek out this handsome man. And then as part of that process as well this whole idea of like we'd like to provide more information architecture and structure to our existing documentation means that we're actually gonna have to identify what all of those sections are and then move all of the existing documentation into those sections which is kind of a daunting task. We're looking at probably about 12,000 pages on just a handbook on Drupal.org that in some form or another will need to be audited and determine should this be part of the theming documentation or part of the flag module documentation. So Tatiana will be working on that at the sprint and she promises it'll be fun for some definition of fun. Otherwise working on any of these things beyond the sprint on Friday, if you there's a the documentation issue queue or the groups.drupal.org slash documentation group are great ways to get a hold of myself or anyone else that's actively working on these things. That's what I got. So that's the end of the session. If you wanna leave feedback you can do so by going to the node on the events.drupal.org site and that's it. And I'm happy to answer questions if anybody has questions or wants to talk more about what's going on with these things. Ta-da. Surprise question. Joe, great job as always. Thank you. Awesome work on structuring everything. I love the basic concept behind the user guide and how it's working. I had a question though as I've been kind of piecing through the code. And for those of you who don't know me I'm Josh Mitchell and the CTO at the Drupal Association so we get to implement the code. Whenever I say there are challenging things that someone has to figure out. He's one of the guys that has to figure out how to be great to ask a question in this forum. AsciiDoc, how is that working in terms of is that helping, hindering? How do you feel about that particular format? Sure. So the question is we're using AsciiDoc as the format to write all of the text for the user guide and how's that process going and do we like it and such. I would say that we use a very limited subset of the things that AsciiDoc can do currently. From that perspective it's been, it works great for me. Like I have no problem figuring out the syntax. It's not all that, it's different than Markdown but it's not anymore or less challenging from my perspective. I do find that like, I've been using Markdown for years and so I have all the basics that I use regularly, memorized with the AsciiDoc. I definitely need to look things up from time to time. I specifically end up looking up the syntax for how do you link one document to another. It has some features that we definitely make use of. Like that for example, the ability to link from one document to another. So AsciiDoc would let me say using a special syntax, link to this other file. That file based on its syntax has an obvious title at the top. So it's generally like the first line and it has a hash symbol in front of it. I'm like this is the title of this document and the document has an ID which is usually the name of the document as well. So I can create a link in one document to another by identifying it by name and what it'll do is it'll actually grab the title out of the linked document and pull it into where I've inserted it into some other documentation. That for example has been really great because I don't have to change the title in one place which is a feature that, I suppose lots of other, so there's AsciiDoc and there's restructured text and there's Markdown and there's a bunch of formats for writing documentation. Yeah, it seems like it works as well as any of the others. I don't know that we're necessarily tied to it. It was the decision to use it stems largely from the fact that Jennifer Hodgson who has been doing a lot of work with this had the most familiarity with that of all the other things that we had looked at. O'Reilly uses AsciiDoc for people who are writing books for O'Reilly and so that was an easy one for us to get started with. It has some benefits like for example once the guide is written you can compile it as HTML but you could also compile it as EPUB or a PDF so we could distribute the documentation in other formats which is kind of one of those like well that's appealing. I guess we'll see if we ever actually use that but does that answer your question? Totally answers the question and then the last thing I would ask are what do you see as the key features for actually implementing that that we're missing right now on Drupal.org? I think the, so the question is what's the key thing that's missing for getting this integrated into Drupal.org? I think the biggest thing is gonna be there's two parts of it, there's the discoverability so how do we get it on Drupal.org in some form that people can locate it so it doesn't just end up as its own separate site that no one ever knows exists and can't get to. So I think there's that and then I think there's the how do we essentially deprecate pages in the Wiki that are now made irrelevant because of the fact that they've been rewritten and incorporated into the guide so getting those two to live well together I think is gonna be quite challenging. Ta-da. Hey great session and I apologize if this was already covered because I came in a little bit after you started. Is there a certain discussion around voice or tone or a persona of how the whole thing will come together because it seems like in other communities that have documentation sometimes there's been a community friction around pronouns or the audience. So have we covered that as a community already? Yes and no. Some parts of that I would say we have and some we haven't. For example, the use of specific pronouns and such isn't something that we have discussed well at this point. Audience on the other hand is something that we have talked about quite a bit at least with regards to the user guide. It's audience for Drupal.org documentation gets a lot tougher. And there is documentation in the documentation. From the audience perspective there's the personas that were developed for informing development of Drupal.org and what we've done is identified, I think we identified the, I can't even remember off the top of my head, but we identified one set of that persona as being this is our target audience. We'd like to write in a way that they will understand and be able to read and have make sense to them. And we use that as guidelines for being able to say, for example, this definition is too technical or it assumes too much knowledge about the inner workings of Drupal. Can you change that? Or conversely like we can assume at this point that you don't need to explain what Drupal is because they already know what that is or they already know what a node is. There is, yeah, does that help? Yeah, so there's, and then in the user guide project there's some written documentation about the audience and the sort of guiding scenario of essentially the story that the guide tells so that we're all kind of referencing that whenever we're trying to create, figure out what content type we're creating or what roles we're creating and why. In terms of the voice, we haven't really figured that part out yet. And that's a discussion that definitely needs to happen. Like ultimately when we go through and edit this whole thing for a consistent voice, what do we want that voice to be? So far we've been aiming for like short, concise, say it in as few words as possible, get the point across and we'll come back and edit it later and probably do it in a friendly way, but yeah. Thank you. You're welcome. Nice work, Joe. Thank you, sir. So forgive my rambling, I'm trying to work my way through this, but you mentioned earlier Mozilla Developer Network and WordPress moving to, you didn't explicitly say more of a model like this, but that was the implication I was kind of getting that it's in version control and the process of contributing is managed in some way. You also mentioned that for Mozilla Developer Network, it's very onerous to do things like fix a typo. This doesn't sound too dissimilar to me from some of the concerns we have on the contrib side of being able to fix typos, for instance, in documentation within modules. And there's a lot of talk about building and improving the tools on Drupal.org to help with that process and make it easier. If that can be done, can you imagine a future where, or do you think that, assuming we can solve those process and technical problems where this is a better way to manage all of the documentation and those 12,000 wiki pages that are the Wild West, sort of, I know this is a long term vision, but that it would be better for them to live in this type of model? Yeah, so kind of two answers to that. Do I have any idea how to do that? No. Do I think it would be awesome if we did that? Yes. I think that part of what this user guide specifically becomes is an experiment. It's our way of testing this theory out that by writing documentation as a project in version control or similar, we help resolve a lot of those things that we've identified as being pain points, like, for example, editorial oversight and review, the ability for someone to suggest changes and ensure that they're changed and kind of all of that. As well as using it as a way for us to have better tools for identifying contributors and such. But it's also, we kind of consciously made the decision to pick just one subsection of the documentation and start with that as a test, rather than commit to saying like, we're gonna rewrite all 12,000 pages on Drupal.org. I'm hopeful that the things that we learn from doing this experiment, whether it's this exact set of tools or not, will help us make informed decisions about how to improve the tools that we're using. And not just be going and making changes to Drupal.org and the tools, assuming that this is a good change, but we actually will have a way of saying, we tried this and it worked or we tried this and it didn't work. I don't know that we would ever get to a place where like, for example, all of our documentation is in Git or that all of it is in a wiki. And I don't know that that's, I don't even know that having it all be in version control is necessarily a good thing because having a more wiki, the free form style allows for a bit more drive by editing, documentation for things that aren't necessarily super important to the entire community, but are nice, helpful notes for me and you for the thing that we were working on together. And I'd like us to continue to have a place for that kind of documentation to live. But I also think that taking the pieces of our documentation that are critical to Drupal's success and putting those into a more rigorous system is an important step for us to make. I think it's interesting that and obviously there are good reasons for this, but we have a model for how we contribute and edit code and we have such a very different model for how we contribute and edit documentation. And it's almost as if, and there might be great merit in this, just think that like, well, any documentation is better than no documentation. But it does present problems where you've got completely eight different pages about similar topics and some are correct and some used to be correct and et cetera, et cetera. So very interesting stuff. I would, as a comparison to and you kind of, I had mentioned that I've previously looked into how other projects are doing this and WordPress specifically, WordPress has their codecs, which is the equivalent of Drupal.org's handbook and the codecs is essentially like a community wiki. They're now switching to, I don't remember offhand what they call it, but basically the WordPress book, which is also community edited and created, but it's kind of like, this is the section that is the like, if you're new to WordPress and you just want the like, I can read this in an hour and be like, know what terms I need to know and make a decision about whether or not WordPress is the right tool, start with the book and it's really well written and it's a great introduction. And then there's the codecs or the wiki, which allows for documentation of all of the sort of more disparate things that are good to document, but aren't necessarily relevant to 95% of people. So that's the model that they've gone to and I think for similar reasons that we're talking about too, in order to basically ensure that people's first experience of the documentation and that the information they get in that first experience is good and correct. Responding to your question about style guides, we do have a Drupal.org content style guide. It's probably a bit stale and probably, well definitely under advertised. And actually like we don't have, because of the fact that like you have no idea when somebody edited a page, we don't have a great way of enforcing the style guide either. So even though we have it and we can say, you're supposed to conform to writing in this way, the only way that that ever happens is if somebody else who came across the page randomly had also read the style guide and said, oh yeah, this doesn't conform. Yeah, so yeah, it covers things like be concise instead of rambling and use American English instead of British English. A British person wrote that style guide. I like you, just clarifying, wasn't me? I didn't, in my two seconds of looking at it, I didn't see anything on pronouns. We probably would defer to something in Drupal Core's help text guidelines if that exists. We right now have content strategist slash manager at Drupal Station and one of his two items is to update the style guide. So he started working on draft and he's really serious about pronouns. So there will be suggestions about that. That's awesome. Cool. Thanks for coming. That's all I got. It's lunchtime now. Thank you.