 I'm going to go ahead and get started so we can start to have this awesome conversation together about documentation. But to start, before we do that, oh boy, I mean, reveal, wait, wait, there we go, haha. I know how to use technology, I swear. So we should introduce ourselves first, right, because that's how you're supposed to do this. My name's Joe, or EOJTheBrave on Drupal.org and Twitter and pretty much everything else internet-related since about forever. And I work at Lullabot. Amber and Greg also work at Lullabot with me, but I'll let them introduce themselves. I'm Greg Dunlap, I'm known as Hey Rocker, I'm all of the internet things, and I've been at Lullabot for about two years, and I was the initiative lead for the configuration management initiative, and I work at Lullabot, I said that already. Amber. I'm Amber Matz, and you can find me on Twitter at Amber Himes Matz, and I'm a trainer with DrupalizeMe, and I've been there for about a year and a half or so. I also need to just kind of, like as a disclaimer, I suppose. I'm a member of the documentation working group for Drupal.org, so we help to sort of formulate the policies and governance structures around how documentation works within our community. In that, so this presentation is reflective of my opinions of documentation, and not necessarily the whole group, so I just put that out there. Though I do think that as for the most part, everyone that is on the committee who isn't here is in agreement. If you feel like following along, you can go to this link and see all of our slides, and I guess you could skip ahead and read them and decide whether you want to stay for the rest of the presentation or not. Or you could, like, if you're watching the video of this and you want to review them at home later, feel free to do so, there's a link for it. What I want to talk about today is documentation, in sort of in general, at a really high level, mostly I want to talk about the documentation that exists on Drupal.org in the handbook section. I want to take a little bit of time to talk about sort of the current state of documentation and things that we've identified as being both weaknesses and strengths of our existing documentation, and then Amber and Greg are going to talk a little bit about some research that they've done looking into how other open source communities handle their documentation and things that we might be able to learn from them and maybe incorporate into what we're doing with Drupal's documentation. In case you don't feel like sticking around for the whole presentation, the short version is that we're starting to really feel like Drupal's documentation, specifically the stuff that's in the handbooks on Drupal.org, could really benefit from some additional, like, curation in editorial oversight. We've seen a lot of other open source projects switch from the open wiki style, anybody can edit anything, to more curated documentation. And we want to kind of talk about some of the reasons that we think that that's a strength and what the benefits might be to Drupal switching to a model that involved a little less open wiki and a little more structure and curation. It's also, when you talk about documentation for Drupal, it's really tough, too, because there's so many different things that make up the documentation. And I point this out primarily because this conversation is really about the documentation that exists in the handbooks. So if you go to Drupal.org and you go to the community documentation section, there's all those pages that make up the handbooks, you can click edit, you know, it's basically wiki style pages. That's the documentation we're talking about here. But there's also a lot of other documentation that's, you know, comprises the full picture of, or the full scope of documentation. API.drupal.org is all of our in code documentation. So that's the stuff that's generated from the doc block comments in Drupal Core's code files. There's also change records, which are, they exist on Drupal.org, but they're not really part of the handbook section. But I would consider them documentation. And change records are whenever a substantive change is made to the way that some system in Drupal works, change records are created to say, in Drupal 7 it was like this. Now in Drupal 8 it's like this, you know, this nice side-by-side comparison of like, you used to do hook menu. Now you do something else, stuff, yaml stuff. We want to talk about the handbook specifically. And partially that's because I think that API.drupal.org and the change records are doing a really good job of what they're supposed to be doing right now. And that the handbook is something that, while it is doing a good job, of the three is probably the one that needs the most attention. So, it's not me. So, talking about the documentation that exists in the handbooks on Drupal.org, some of the things that we've identified as could be improved. This is, you know, this is that tricky, like, I don't want to be like, this is crap, we need to fix it all, because there's a lot of really good stuff too. But so some of the things that I think we could be better at are curation and review. So, one of the things that you run into when you've got a giant wiki is anybody can create any page they want at any time. And so they do. And so you end up with like tons and tons of different pages, some of which cover the same content, some of which cover the right content, but they're not in the right section. So you wouldn't actually be able to find it and so forth. Having additional curation or someone having people who are fulfilling a role of saying, even if it's just saying, here's the table of contents that we need to fill in and the order that things should be in. Someone that's familiar with the system at a larger scale, maybe you're trying to document the theme section. So this is currently the case with the theme section for Drupal 8. It's like there are a bunch of pages that are really great that explain things. And then there's a couple of pages that probably should be there but don't exist. And it's kind of like, well, nobody that's not familiar with the system already knows that that page doesn't exist, right? You came to read the documentation because you don't know how it works. So having that kind of oversight for people saying, you know what? We're missing things here and there that need to get filled in. And then also one of the things that we miss a lot is sort of a review process. It's not because you can't review documentation, right? Like anytime somebody makes a change, I could certainly go and locate that change and review it. It's just that there aren't like formal processes in place to do so. The comparison would be something like the documentation that appears on api.drupal.org, which does go through a really rigid review process. Because it's committed code, so it has to go through the entire like issue queue process of reviewed and tested by the community and so forth. And I think that as a result, we end up with better documentation or at least more consistent quality. Because all of that documentation is reviewed by a few people. On the handbook, it's like some pages are and some pages aren't. And there's really no way to know what was or if it needs review and so forth. There's like a couple of other things that I think really stand out. One of them for me is how many times have you been to a page in the handbook? And it's like, this particular page is about how to create an info file for Drupal 6, 7 and 8. Well, I mean they're kind of the same, but they're kind of different. So you're reading through the page and it's like, if you're working with Drupal 6, read this section, but skip this section and then read the section below it. It's like, this is really complicated. And so I think that there's a need for us to be able to better version pages of the documentation. So we don't end up with this issue where you've got one page that's trying to cover all previous versions of Drupal for a specific piece of content. Another thing that is identified often as being problematic with documentation is people want to be able to translate it. Like we want to increase the adoption of Drupal. And one way to do that is to have awesome documentation that exists in other languages. So people that aren't speaking English as their primary language can also easily get involved. But with the systems that we have in place for Drupal.org right now, that's pretty tough. And then there's also sort of like beyond just the technical ability to version a page or translate it. I think one of the things that we could be better at as a community when it comes to documentation is celebrating the people that contribute to documentation. I also, I don't think any of these are new issues either. I think these are things that as a community we've been talking about for a long time and just things like, how do we celebrate that so and so put a hundred hours of their life into organizing a camp. But you don't really have an easy way to quantify that. You end up in these scenarios where somebody puts up a tag cloud of all of the people that contributed to Drupal 8 core. And that's awesome, except for it's only generated from the commits. And so there's a lot of people that whose names aren't appearing in that. And it has some weird implications. Like it makes it more appealing to want to work on things that are in code because you can do things. You can say, hey, my name's gonna be on the tag cloud or this is a trip that commit was attributed to the company that I work for, whatever the case may be. We work on this. This isn't something that we're like, man, it never happens. As a community, we are always trying to solve this problem and be better about celebrating everyone that works on. Contributions, but we could always be better about it too. So some of the things that we're doing in order to address these issues currently and what the priorities are for the community and the documentation working group, obviously Drupal 8 documentation is a big thing right now with Drupal 8 hopefully coming out. When Drupal 8 comes out on Saturday, no, no, no, I did not say that. Dang it, now this is recorded. But there's a big push right now to make sure that the documentation for Drupal 8 is really good so that when it does come out and people start adopting it, they can figure out how to make a theme or how to make a module or how to log into their site, whatever they need to do. So that's a priority right now. The as changes are being made to the infrastructure for Drupal.org and kind of the software teams that are the DA and everyone that's making changes there. Some of the things that we're trying to do are add the concept of the ability to follow or subscribe to pages in documentation. For me, the big thing would be I want to be able to mark a page as this is something that I know a lot about. So if somebody edits it, I'll get an email that says, hey, when Greg edited the theming page, you've subscribed to it, why don't you go and review those changes? So this helps to deal with some of that review thing that we were talking about earlier and just a little bit of ownership of sections in the documentation. Do you have a question? Yeah, so all of these link to either issues on Drupal.org already or the DA docs is the tag for all of the issues on Drupal.org that are related to creating handbook pages for documentation. There's the documentation issue queue that has a bunch of like, it would be nice if we had a page that covered how template preprocessors work because that's missing and it's important and that links to a lot of those. Just click the link. That's why I gave you a link to the slides earlier. So ownership of sections of the documentation and giving kind of like establishing maintainership or responsibility. One of the things that we run into now is it's really hard to go in and say, this section over here, I'd like to take on being responsible for and ensuring that the theming section is up to date. You can, but it really just comes down to like, well, what I did was I bookmarked all of the pages in the theming section that I care about and I just make sure and go back to those every couple of weeks and see if they've changed or not. And it works, but we could have better tools to do that and we're working on that. You can get a complete list of all of the sort of like priorities and things that we're working on at the moment on the documentation working group goals. I think one of the things that becomes obvious very quickly is the changes that we're making right now are all sort of like incremental changes to your existing tools. And that's awesome that we're making them better. But I think part of what we're going to talk about next is like, what would it look like if you just deleted documentation and started over? What would it look like if five years from now, what's ideal documentation in the future? I also, I don't want to just stand up here and be like, doom and gloom, documentation is like going up in flames. There's actually a lot of things that we're doing really, really well too. I think api.drupal.org and the documentation there for Drupal 8 is phenomenal. There's been a lot of additional documentation about like topical overviews and it's gotten like the changes to the page just to make it easier to locate and navigate things that are really great. I think part of the reason it's so great is because it does go through a bit more of that curation process as it's getting written. I think the change records are great and then we're doing a really good job of making sure that those get created for important issues. I also like that change records have this ability to basically say block an issue from being closed because it's not documented yet. I think that's a pretty powerful concept. Mostly I want to make sure that any changes we do make or we talk about making that we also take the time to be aware of the things that we're already doing really well so that we don't just steamroller over those and forget how awesome the things are that we've already established. And then there's the sort of like if I'm going to step back and figure out like what do we want to change and how do we go about having a conversation about documentation. I start to think about like what questions do I want answers to or do I want to be able to answer that I can't and two of them that are really stand out for me is I wish I could go to a page on Drupal.org and identify who has claimed responsibility for keeping this piece of the documentation up to date so that if it's out of date or if I just have questions about it I know who to talk to. And right now the best you can do is just kind of see who edited this page last and most of the time all they did was change a typo like if I contacted Greg you'd be like I actually don't care it just had a typo and I wanted to fix it. So I want I'd like to be able to answer that question a little better like who's who's responsible for the Drupal 8 user guide who's responsible for the theming guide and making sure that it gets done and I'd also like to be able to answer the question like how do we is there ever a process in which the lack of documentation is able to block a release of Drupal. Is it responsible for us to release Drupal 8 without also having a stellar user guide already written to go with it. I don't I don't know the answer to that question and sometimes I think yeah sure let's release it and then the community can over time improve the documentation and then sometimes I think well it shouldn't like you wouldn't ship a product without a manual that's well written. Is that something that we want to do? Okay okay maybe well written was the wrong. But what I want to do is let Amber talk for a little bit about some of the research that she's done into how other open source projects handle answering some of these questions. So last year at Write the Docs I got to meet a person that's on the WordPress documentation team and I took the opportunity of emailing him and asking him some questions about their process of documentation and what kind of things that they've been working on and what kind of changes they're making. WordPress as you may or may not know they have a community wiki which is and anyone can edit anyone can add it add to it and it's called the Codex and they did a community survey about 18 months ago asking people their satisfaction level with the Codex and it was very poor so it's out of date it's just this behemoth of documentation that is hit or miss not unlike a documentation piece that we have on Drupal.org and so what they decided to do is start to move to curated guides that go through an editorial process that are written by the documentation team and so these handbooks and there's some terminology differences with what we call handbooks and what we call guides and what WordPress. So in WordPress's case handbooks are guides that are written by the documentation team. They've identified a list of guides that they think would cover what you need to know as a WordPress user or developer to be able to make use of the software. These are the things that you need to know here are the different guides so they're in the process of doing this and they've they've started this process they've completed some of the guides and you can see on their documentation team website what they've done already what's on the list what's in the future etc and so they're in the process of replacing the Codex with these handbooks. Right now they coexist and they probably will coexist for the foreseeable future. So here's an example of one of the handbooks so they have a handbook for plugins and as you can see there's some nice navigation there's a table of contents it's a product in and of itself it's its own entity and it's been it's gone through this editorial process it's not that anyone just added these pages like as part of a book you know that that we call in in Drupal it didn't just serendipitously end up like this it was planned it was written you know it went through the whole process that you would expect for a first class product and here's the WordPress documentation team home they have a blog you can see what activity they've been working on they have information about their weekly meetings and how to get involved you can see what they've been working on and they've got some links to to get involved with that so they have a very distinct you know home page this is this is what's going on with documentation and what I got from learning about WordPress's documentation team efforts is that what I learned is that they have a core group of volunteers that work on guides now some of these volunteers their companies pay for them to work on the documentation team halftime so they work for an employer that's a WordPress you know vendor and just like we have companies here in the Drupal community that pay core developers to work on core they are paying for documentation teamwork which I think is admirable and we should we should learn from that I think that's excellent their meetings progress and updates are transparently communicated on their doc team public blog this isn't this is an unlike what we do here is a documentation team but this is what they do it's on their blog and you can see what's being worked on now what's complete and what's planned for the future and what they've noticed is that with more accurate and helpful documentation with these guides there is a higher level of satisfaction so people can actually go and use this documentation learn what they need to learn and successfully use the software which is the whole objective right the next case study I looked into was the Mozilla developer network they're they were a huge presence that read the right the docs last year and they will be this year as well it's next week in Portland actually I'll be going to it again it's an excellent conference if you're in if you're a tech writer or interested in documentation I highly recommend the right the docs conference put that on your radar and the Mozilla develop developer network here's a screen cap of the home page so they have information for people that are for who people who are learners and they have these learning pathways so those three boxes at the bottom you know you can learn web development you can get the tools that you need you can develop with it so they have these pathways to find for for people who are using the tools they also have two different callouts one at the bottom of the home page and also they have like a little call to action like add for that lack of a better word to invite people to contribute so they are actively recruiting contributors to their effort I mean that's their whole thing that this documentation this website is completely run by volunteers and is run by the the community and the world really like anyone can can join and so they have a definite invitation to help improve MDN and contribute so when you click on the the getting started or any of these links here that takes you into this contributing to MDN section which is it just it almost brought a tear to my it was so beautiful so it just it's this wonderful repository of well organized information for how to get involved with contributing to MDN and what I learned from this section is not only are you guided as a new contributor for exactly what you need to do to write a page or to review a page or anything they have many different roles defined for people who want to contribute they have mentors they have admins they have topic curators and topic drivers when you go to the topic driver topic curator page you get a table of here are all the topics that that were about you know that that deal with Mozilla or web development and here's the person that's in charge and here's their IRC Nick and here's how you can get involved with them here's the channel you know like this is where to go this is who to go to and there's ownership of these topics and there's also if for these topic curators if you're done and you want to step down just notify an admin and you know and so the process can continue so there's no like well your chain to that topic now for the rest of your life and you're gonna have to like go down in flames with it no it's like there's there's always this there's this information for contributors of all different levels and I think that's just excellent it really makes clear how you can get involved who to ask for for help and what their system and what their hierarchy is so it's defining pathways for both learners and contributors the their extensive documentation guides for contributors including style guides how to document specific things like a CSS property because that's a common thing you'll see on that site and these various roles and responsibilities which I think is a great model so you have you don't have someone that's doing it all you have these different roles and responsibilities you have admins topic drivers curators mentors writers editors reviewers so whatever it is your time or commitment or your skill level you can get involved in any number of ways and I think that that's great because that's one of the daunting things about getting involved with Drupal is if I say I want to do this does that mean my life is over as I know it like does that just mean inevitable burnout does that mean that I'm going to take on more than I can and giving up those roles and responsibilities and letting people plug themselves in where they know they can and they're able is really great it's a great model the other thing that I notice and it's semantics but I think it's an important distinction is that their documentation pages are called articles and what do you expect from an article you expect that it's been reviewed by someone someone looked at it someone did spell check someone did you know that it was reviewed for content and for copy editing and it also exists in a context with other articles it's organized into some sort of architecture it's what you would expect and so I think that the the lesson that I learned from MDN is that they are treating their documentation as a first-class product they know that if people can't learn their technology they're not going to use it they're not going to develop with it they're not going to contribute code to fix it or improve it so they treat their documentation as a first-class product it's this site this MDN site that is the most one of the most well reputed and trusted sources of information for web developers on in on the internet so because they have done this process because they have these roles and responsibilities they have this editorial process they have documentation for contributors of all different levels it has resulted in a website that has the highest quality of information for developers and I think we can really learn from this back to you Joe so I think what all of this did for me and I it's this whole like we the idea of creating more editorial control and curated documentation for Drupal.org isn't new at all it's something we've been talking about for years I went through the issue queue and it was like like the first time somebody brought this up was like eight years ago I'm like huh that's interesting and you can actually like over the last eight years you can track lots of different efforts in order to the people interested in making that change from sort of the the more free-flow handbook that we have wiki to something that's a bit more curated and I think one of the things that we've always really struggled with is it's it's hard to define exactly what it is we wanted to do as a community like there is there are some things that are really great about the wiki and I don't think it's ever going to be something we want to just get rid of totally like you're always going to want to be able to allow people to create documentation for their individual products or just to augment the existing documentation with information that's maybe important to them or just you know within a a more niche area within the documentation but there's also a lot of benefit to saying for certain segments of the documentation we should make sure that there we're putting our best foot forward whenever we write that content so you know maybe it's the the Drupal 8 core user guide that the things that you can do with Drupal core saying like let's let's take the time to replace certain key sections of our documentation with things that are a little bit more rigidly controlled and structured what I struggle with this sometimes though too because the flip side is I love the fact that I can just go to any page on Drupal.org and I can click edit and fix the typo and I think that that's something that is a community we've really come to appreciate so those two things are kind of those opposed though right you it's great that anybody can edit anything but it also means that anybody can create a new page that's a copy of an existing page that's a copy of an existing page that was created the day before Drupal 7 was released that documents all the stuff in Drupal 7 right and it hasn't been updated since and so those you end up with like those two opposing forces but I think that that what we're as a community that the point that we're at now is sort of like we don't really need to necessarily make infrastructure changes like we can do a lot within our existing infrastructure it's more about like changing the policies and the way that we think about like who has control over certain sections or should should we remove the edit button from the Drupal 8 user manual so that it is more controlled what and what does that look like for our community so that's kind of like my thinking forward to like what what is documentation look like five years from now is I would love to see something where you you have a couple of people who are committed to maintaining certain guides within the documentation that are experts in that area I would like to see that documentation maintained in a way that made it easy for when Drupal 9 comes out you could effectively fork the documentation and say all right now we're starting the version of this book for Drupal 9 and we'll keep it up to date in the same way that we keep api.drupal.org up to date as changes are made throughout time you don't end up in the scenario where you know Drupal 8 is somebody told me was coming out on Saturday so apparently Drupal 8 is coming out on Saturday and our documentation isn't ready yet because we we haven't done as good of a job of keeping it up to date during the development process but I also think that there's like in order to make changes like this there there's sort of like significant hurdles to overcome that are more like less infrastructure hurdles and more like community political hurdles I a year ago Jennifer Hodgden proposed hey let's put all the documentation and ASCII doc and and and get it'll be great and I was like no that's the worst idea ever we shouldn't remove the edit button and now like eight months later I'm like huh actually I kind of like that idea like so so the change is hard and it takes time and you have to get in a community like Drupal where it's all open source and you want to get buy-in from everyone you it you need to be able to make sure that you can put forth a good argument for why that change should be made so we have discussions like this in order to try to engage with the rest of the community and try to get a sense of like like is this a good idea are we going in the right direction if we do go in this direction like how do we define which parts should be a curated controlled guide versus which parts are fine just being a wiki like there's there's you know let's say there's 12,000 handbook pages right now we certainly don't need to convert all of them to a very curated system but we need to be able to define which one should be converted which one shouldn't it's doing something like writing a book is a huge undertaking and being able to like standing up here and saying sweet we're going to change the policies and we're going to do things different is one thing and then actually writing the documentation is a totally different process and somebody needs to take care of that and so like how do we how do we find the people that can curate the documentation and that have the time to do so or how do we fund someone to be able to do so and then of course there's the ongoing maintenance part of it where you've created this book and as soon as somebody changes something is in core it's out of date and you need to make sure that that stays up to date so you have to get the documentation created in the first place but you also have to keep it updated over time so that lots of challenges to getting something like this adopted but I also feel like I've had a lot of conversations about this recently and even despite the fact that this has come up like many times over the past few years it feels to me like we're kind of getting to a critical mass where people are is interested in like yeah that may be maybe doing a more curated documentation is the right right path forward it really what it comes down to is like these are just some of the ideas that we have in ways that we think it could be better but it at this point it's like how does the community feel about this like how would you guys feel if if I said you know what starting tomorrow there's no more edit tab on this section of pages in the handbook I feel like a lot of a lot of people would be really upset about it and some people would be like oh I get why this is a good idea and so trying to discuss those things and what we'd like to do is hear from other people if like thoughts like curated documentation good idea bad idea what are your concerns about moving to a system like that I'll start the discussion because I'm standing up front I didn't I sorry I I actually brought the idea for this talk to Jo and Amber and it's really great because then they did all the work and put the thing together and I got to just sit here and take the credit for it but but I actually have been thinking about this issue for a long time because one of the first things that made me think about this was when I was doing research for CMI and how other systems did configuration management I went and looked at the documentation for PLONE which is another open source CMS and they basically got the equivalent of using Drupal as their as their guide and it's curated and managed like this they actually manage it now in GitHub and anyone can issue pull requests and they've got a centralized team to manage it but it made me realize that we as a community have basically outsourced the documentation for how to use our project to commercial book authors and as a community that and the ideals of our community I think that's kind of crappy that doesn't really match the ideals that our community is around and that we want to build for Drupal and so I'm a really I'm a really big proponent towards towards making this change and I feel like I feel like heading into Drupal 9 we've got a real opportunity to kind of like start fresh I'm sorry heading into Drupal 8 oh my god I can't believe how many people have been talking to me about Drupal 9 this week it makes me makes me makes my head want to explode heading into Drupal 8 I think we've got a real opportunity to start something fresh and something new and and I think that I think that authors will really like it because right now I've talked to a lot of people who around documentation of CMI and one of the things that they bring up especially like people who are real authors like real professional writers is that they're they're really reluctant to write for Drupal.org to write something professionally because they have no idea what's going to happen to it they have no idea what people are going to do to it that they constantly have to be monitoring it that it's going to decay over time and you know I just feel like we we can do a lot better as a community that is our documentation pages than just you know letting anybody write them and rolling in comments once in a while that's all I've got to say now you guys can talk. A really good talk I think really important talk and one thing that I've I've been looking at the space for a very long time like and I'm not well I've got a few edits but I am by no means a real documentation writer myself but for some reason I'm really excited and interested in this space for a very long time. That pretty much sums up me too. Yeah so I just come from the DTABof that I organized at Hock we were talking about structured writing and technical writing in Drupal and how we can make that better. Now there's different parts to this one important observation I think is why are we not doing our documentation the way we do our code? Like and what I mean with that is our code is being built by the community and and also by the commercial players in the community while our documentation is built purely on altruism and it's purely built by people that are too good for this world. I've done talks about the angels of our community that are burning themselves doing stuff that goes nowhere while if we would approach this on a granular way so that we get topics that can be reused in our commercial documentation we would be able to encourage our commercial community to also chime in and like start building topics that are reusable for both the project and the commercial level of the documentation. So if you can make deliverables that incorporate topics that have been generated for the community but then can be used on a commercial project we can do the same thing that we have with modules today where people are doing patches because it's in their professional business interest not because they're so good that they think that they should you know go and do this thing for the community. Like you know we by all means we need to keep that also but I think that there's a lot of commercial power that we can bring that we can bear on to this problem that we are currently not doing. I think a good example of that would be like my role where I work on the Drupalize Me team at Lullabot and I spend a lot of time learning how certain systems in Drupal work so that I can create videos about them and I do so by going to Drupal.org and reading the handbook and half the time the page isn't there so I have to go and do all this research already because my work is paying me to figure out how this thing works I might as well write the documentation and stick it into the handbook and so those sort of artifacts of the work that people are already doing for client work or writing a book or whatever how do we reuse those in a better way? Yeah, so I think that the so and I would not remove the edit button I think that's the like this is what the Python community is doing is the I think it's like edit me on GitHub and then you just use a wiki kind of model where people can like they don't even know what they're doing they're just editing the documents but what they've actually done is they've submitted the pull request that somebody will review and then accept or not accept and incorporate so it's like it changes the way that the edit functions in that when an edit is made you're also aware of the fact that it's going to go through some kind of review process first yeah which I think is an important like and that's one way that you could certainly address this is like don't remove the edit button but change it so that your edit isn't made live immediately and I we were actually talking about this earlier where one of the things that I think happens a lot with handbook pages is people are intimidated to edit the page because they're not confident that they're right and so they so you end up with these pages that have 30 comments that are like the actual good material is in the comment and then you've got 30 more people saying just edit the page and add the material and I think a little bit of what happens is people comments feel less intimidating because it's okay to be wrong in a comment but it's not okay for the handbook page to be wrong in theory and so having having a process where you click edit and you know that before that change is made public someone else has taken a look at it makes it it's like it helps overcome some mental hurdles I think so I think that's but to be able to do that we need to really go and restructure the content so that it becomes more modular and reusable so that it's not like this is all the documentation about how to install this module but there's like this piece here that explains how to do that there's that piece that you could potentially reuse as conceptual content in another deliverable and then the last part that I wanted to bring up is I think that as a community what we need is a distributed like a sort of cloud of documentation where Drupal.org is just one deliverable and maybe we have a tool that allows us to go and search all through well maybe this is on GitHub or some other hosting tool where you can go and discover topics that have been written about something that you require and then you can like plug them into your deliverable that builds that deliverable from all these distributed items that are out there and then you could have like I want version 5 of this topic that was created by this person and maybe I go and fork it and that's kind of like the Git kind of flow or even things like like one of the things that we struggle with right now is there's a lot of really great documentation in the hook help implementations modules in core and what ends up happening is people like copy and paste that documentation onto Drupal.org and then one or the other gets updated. Yeah and all of a sudden it's like well the module documentation here says one thing but here it says another thing because you don't have that easily reusable. Yeah. And you don't have the organization mirrored either. Yeah. So yeah. So but I really think that we need to get this out of the hands no we need to open this up. Right now it's only the alt-rists that's not good enough. We can do much much better like this is the power of our community is that we can take commercial interests and use them for alt-ristic move motives and I think this is what we really need to do. I actually had a long talk with Jennifer Hodgson about that once because obviously I did a lot of fundraising as part of CMI not obviously. So for anybody who doesn't know when I got the configuration management initiative one of the things that did was I was being funded partially by the company that I worked for Node 1 who no longer exists they got absorbed and turned into our Wundercraft and and after I left Node 1 I was wondering how I was going to maintain the level of contribution that I had when I was being funded and so one of the things I did was I put together a fundraising drive and I started approaching companies to raise money to fund me to develop a CMI and I eventually ended up raising $50,000 but one of the things that I learned about that fundraising that's really important is that you have to figure out it's not you if you approach fundraising purely from the altruistic level if you say please fund me because it's good for everybody that's not that doesn't that doesn't fly some people will do that but that's not how you get how you get the sort of you know massive funding that I was able to get you have to find the people whose commercial interests are benefited by the work you're doing and that's really and I was talking to Jennifer a lot that about that it's finding the people whose businesses depend on what you're doing because then you can help them and make the economic argument to them that they're saving money by giving you this money to do the work that they need so for me for CMI one of the places that I was able to be really helpful was with hosting providers because CMI is going to allow them to way more easily build tools that they can they can use to sell to people developing Drupal on their hosting platforms and because they're product based and not services based their viewpoint in terms of investment is much longer term and so you know when I was talking to Jennifer I was talking about one of the places that you could approach is the training companies for exactly the reason that you just said because there's real economic benefit to these training companies to having these documentation that's written and good and in a place that they can use so that's my little thing about funding that's all one thing that I want to bring up you mentioned a few case studies here but one bit of documentation you didn't mention was Ubuntu.org and the approach that Ubuntu.org takes is there is I don't remember the exact words but there's like the community documentation like the community help guides or something they call it and then there's the official Ubuntu documentation and I think that's the way that you can approach this that you can still have that wiki style thing where people can click the edit button and they can go do their thing right away and they've got a channel where they can contribute but then you have the official documentation that ends up being more of sort of this curated stuff that's going to go through the review process and so that's what I'd like to throw out there because I feel very strongly that I'd hate to see the edit tab disappear because I think that's a it's a really convenient way that people who maybe aren't coders can have an opportunity to contribute to the community and if that just gets locked down I think that's going to have some serious negative consequences so just the idea like the official documentation and the community help type stuff and just looking at it I don't think any of us want to throw the handbook in the garbage and burn it to the ground I think it's just sort of business in the front party on the back kind of thing it's a joke there's a lot of websites that when they started putting their articles on the front page and then putting the comments behind in tabs that's what they called it business in the front party in the back so that the comments were separated you had to make an effort to get to that part but their official stuff was still in the front sorry that was probably a nerdy media joke I have a question for you Joe yep okay you mentioned earlier you were part of the documentation working group is this an open group that anyone can be a part of or is it sure so the documentation working group is myself and two others currently and it was formed a little over a year ago and basically we were those of us that were really actively involved with documentation at the time were asked to come on and be part of this to help govern some of this type of policy and decision making around documentation the working group is anyone can attend the meetings the meetings are open and we'd love to have people join and partake in the conversation becoming a member of the group there's a bit more of a formal policy you can read about it sort of in the governance section on Drupal.org but it's in the way that those committees tend to work it's sort of a people are selected to be to help out with the committee all the committees though are open and we'd love having people participate in the discussion specifically the documentation working group if you check out offhand I don't know that this is the problem with Drupal.org I haven't memorized the URL for the page that you need to go to and I don't actually know how to navigate there either so you could search for it on Google and get to the the documentation working group page and there's information about how to find out when our meetings are and how to participate so oh okay and just a comment I think a larger issue is just about standards and consistency because I feel like people are doing their own thing I'm not trying to be stringent or I agree and so and I think what's interesting about that is like we do have standards and we have documented standards for you know voice and ways of writing but we don't have any review that enforces those standards because I could just go and change the page to you know a bunch of lol code and no one would ever know unless they happen to come across that page sometime. Right it's really about conceptually changing the model by which we have it because one of the reasons that the API documentation is so great is because we have an extremely strict not only do we have an extremely strict set of standards for core but we also have an extremely limited number of people who can commit code to core so we've got that that barrier through which code and documentation of the code can't go through unless it's really up to snuff currently we have the we have the style guides and we have the standards about how it should be in place but we don't really have a good way of enforcing it other than me deciding I'm just going to take some time to go edit this because it doesn't match and then tomorrow anyone can change it to law code anyways yeah and um what's what I liked about the MDN is having the different roles so you can be a topic a topic expert but maybe your English isn't so great and your writing the skills aren't so great but you can still write that draft get the information out and someone else can come along and clean it up and I I love that idea of like this information is golden it's just making me cringe because um it's not structured it doesn't have the right voices and have the right grammar it's got it's full of spelling errors that's distracting and it it um it makes people question the authority of it and and that's why it's not because we're being nitpicky and being snotty about it it's because it questions the authority can I really trust this can I learn from this and so that's what I love about having the different roles and having the process because it gives people an opportunity to contribute how they can and what where their strengths are and lets others come along and improve it and the end product is trustworthy and reliable thank you thank you thank you so many comments to make but I try to be brief and not make all of them one is um you were saying about the the you know you think this time in the last eight years you know we might actually be moving to to actually doing something um earlier in the week there was a a bof that was supposed to be about crowdfunding online training and was attended by a number of different sort of training companies and individuals and things and what happened throughout the discussion is by the end we had decided what what was really in the business in in altruistic interest both was actually to look into okay maybe we can crowdfund paying people to do documentation at driple.org so that was sort of one thing the other is just kind of the aspect of you know that anybody can edit it so you could be replaced by law text I have a background in history I was I was trying trained historian and there's some subjects in which I am the subject expert and periodically people say hey come contribute to wikipedia and I say no because you know they've already plagiarized and bastardized my articles and we've done horrible horrible things with footnotes to my article like Greg was saying I think it was Greg that mentioned that like it's it's hard as a say you're a book author to have like spent a lot of time carefully crafting that documentation and then and put it out there in a space where anybody can come along and change it and I mean it's so easy to like effectively change the meaning of someone's writing just by changing a few words especially you're still being credited with having said it yeah right and then then what happens is everyone goes oh you said that because your name is attached to the node where it's like no no no Greg said that yeah so and then my my third one is you know I think the comparison to what we do with code is really apt but and in sense I think you know I don't think necessarily want to take away that that the ability for people to contribute but I do think you know kind of following that that code model where you know there's a place to discuss it there's a place you know you can make patches they get reviewed they get put in all this kind of stuff so we have that kind of control but we still have that everybody contribute but one difference that I think there is that would need to be addressed is that the people we who you know this is their way to contribute not codey to people so the tools for them to do what happens already for code needs to look like human liberal arts you know non-techy type of tools so maybe it's not an edit button but it's a you know you know submit editorial correction or I don't know what and then it goes to something but it's still still techy that's actually you know that's it see he he's gonna know the the like media terms that they use no I don't but I mean that's actually one of the great things about github right now is that you can just click an edit button and you get a visual editor and all of the things about turning it into a patch and making a pull request happen behind the scenes you don't know anything about it and that's one of the reasons that a lot of these projects have moved to using github for their documentation is because that tooling's been built they don't have to do anything with it at all and I also think though at the same time you want the easy links to somewhere where this is being discussed so that you can find out that somebody else has already submitted a patch that is doing exactly what you would do so you don't duplicate the work but I like this discussion and I'm very excited I just wanted to make a comment about the funding again because that's my thing I don't believe in crowdfunding things that are critical to our project I believe that this should be staff positions at the DA or somebody else because because one of the things that happens in our community and I think it's really garbagey I'm going to go on a little bit of a rant here I've heard a lot of I have three minutes the idea that we pay people to do a thing or that we contract people to do a thing is I think really garbagey and I've heard a lot of talk about people being worried that so many contributors are becoming employees that companies are employees at the DA and I really think that that's awesome because the idea that we have a multi-billion dollar industry that is being built on the backs of volunteers is not only crappy I actually think it's unethical and immoral we should be giving people who bring the value of these companies jobs real jobs with benefits that they can go to every day and get paid for here here hi my name is Oren I'm a young white man who grew up in America and my mom taught me to make web pages and HTML when I was in middle school so I feel very very lucky and because of that I think documentation is really important because not everyone is as lucky as me so I think that thank you both Amber and Joe especially for making this great presentation this is like one of the most important things about Drupal is that it taught me a program I didn't know I was a programmer when I was using cck and doing things with views back in the day but I it was like a gateway drug and now I'm I feel like that's awesome the power user because of that I feel like Drupal empowers people like that in a unique way that no other platform is attempting to do and I have a bone to pick because this discussion says iteration versus a fresh start and I think that's a that's a false choice I feel like we can do this right now we can do both of these things we can iterate on what we have and we can design the institutions that will guide our future right now and so I want to invite people tomorrow to like brainstorm at some point during the code sprints that people are around to like edit whatever it is maybe it's making that wiki page yeah I'll be there tomorrow for sure and I'd be happy to sit down and talk more about this and I think there's like work on things just just one more last look at some people behind me I think that there's like we could either go into you know what are some specific tasks we can do to clean up the existing pages what are some specific things we can do to make it easier for people to find documentation what are some specific things we can do to make the working group better you know to find these roles like mentors and curators and things like that like this is like the crucial work I think here I think that's a key thing to to point out too it's like again none of this is new and a lot of it is already stuff that we we say we're doing we already say we have a style guide we just don't have a way of enforcing the style guide you know we already say like it's possible for all of the edits to get reviewed but it would just be a matter of going through all 12,000 pages every day and seeing if any of them changed and need to be reviewed and so like these things aren't impossible and we could start doing them but I think we also need to have tooling that supports it and makes it easier so like the previous speakers I have lots and lots of ideas and I'll try to limit myself to a few useful things so let me say lots of ideas first of all that yeah I totally agree with the what a lot of people have said that we want to keep the free-willing open edit button but I also think that we desperately need a separate curated section which is going to get pull in the good stuff from from that free-willing stuff second thing I want to say is that I'm thinking of the keynote this morning and the stages of open source and that applies too to the documentation and we want to get to a point where the open source documentation is really great and can be used as a basis for further commercial uses so that there's an incentive for the O'Reilly's and whatnot and the Lullabots to fund the official community documentation as well as their own value added stuff as our community's like gotten bigger and grown up and there are more businesses involved and more money involved over the last few years we've done a lot to iterate the way that we do core development to help facilitate that like things on Drupal.org to allow for crediting organizations with contributions and so forth and now we need to grow up the way that we do documentation in the same way like the recognition of you know what we're not we're not just a bunch of ulterists who do this in our free time anymore and that that's not sustainable and totally it's a matter of like your project goes through various phases as it grows and documentation is at a new phase. Yeah and another thing I'd like to see is more structure in this discussion so we've mentioned a few possibilities let's do it in ASCII doc let's keep it in Drupal because my god we're Drupal and every problem looks like a nail and I'm sure there are other ways that it could be structured so we have lots and lots of solutions suggested I think we need a clear set of design goals. I agree I think one of the things that we've struggled with in the past is we very like as developers we very quickly jump to like engineering a solution right and so we're like oh let's convert it to ASCII doc and like I know how to write the code to do this and it's like well that's great but so do a lot of other people let's define what the requirements are like you know the requirement is when somebody clicks on edit the change that they make goes through a review process personally I don't care how that's implemented as long as that's what happens just as one example one goal might be that it be translatable and that imposes all sorts of restrictions that drastically reduces the scope of how much there's going to be and how easy it is to to make updates because you're you can't just update it once you have to update it and then translate it so that that's one goal that may not be an overriding goal it may conflict with other goals but but let's come up with a list of goals and discuss how important they are let's come up with a list of solutions and see how well they satisfy the goals let's start implementing some of those goals and that I want to segue into my last idea again tying it into this morning's keynote we saw all these sides with exponential growth and you've got to think about the beginning of those curves as well as the end you know the fundamental idea of exponential growth is it starts off small and then it gets really big so when it's in the small case we can say let's try it in ASCII doc let's try it as a separate Drupal site let's try some other implementation let's write a few pages a few chapters in each one of these and see how it actually looks absolutely I think there's some I don't know if you were in the presentation earlier this week about some of the content strategy work that's going on for Drupal.org but there's a lot of work that's been going into defining better ways of architecting the information on Drupal.org