 Thank you very much for being brave for documentation talk. Before I begin, I would like to tell you how we are going to finish. So I'll give you a glimpse of how documentation is managed in a large open source community, the WordPress community. I'll add a few tips, make a couple of strong points on the importance of documenting everything. And you'll agree, find it relatable. That's because I'm skilled in making strong points. And you will even ask a few questions, maybe start reading some of the pages I recommend. And tomorrow you'll go back to old non-documentation life. Unless you are already a member of open source community or considering becoming one, but there is no handbook on how to be a member of that community. Or you're trying to use open source software in your project and the latest version in documentation is three major versions ago. Or you are developing this magnificent software and you made it open source and set the license to allow everyone to use it, but it just doesn't get any contributions from random good people as it should. It's open source for Christine's sake. And now that we have established who this presentation is for, I hope the rest of you will want to try some of these roles by the end of the presentation itself. Being a part of open source communities both liberating and enslaving you're going to love it. But first, I want to address a few misconceptions regarding documentation code should be self documented. This kind of thinking is rather elitistic and creates a community in a bubble. You're inviting only developers and only those developers who understand your code and the structure of your project. You're really inviting yourself and you're missing out on different use cases for your project, new feature proposals, new contributors. You're limiting the growth of your project in every possible way. The next one. It's obvious how to use our software users will know. Even if your software is yet another email client, there will always be enough new users who will not know how to navigate it and will not use it properly. And being both developer and documentarian, this is probably my favorite. Real developers have no time for documentation. They just write code. If you ever try to write documentation, you would know just how in depth you need to understand the software and how many skills you need to be able to pass that knowledge. And once you try and realize this, you'll know for a fact that only real developers can write software developer docs. And these are just a few of many. We don't have time, unfortunately, for all misconceptions. And documentation is like exercising. You know, you should be doing it every day for at least half of hour. But if you don't have that time, you should do it for an hour. And of course, there are many challenges once you decide to write documentation. If it's never finished, that's something to make peace with. It is never finished. And you really have to commit to it because this is how the world looks like without documentation. It is interesting. Yeah, not very useful, though. And this user obviously knows how to use this device. And regardless of how many people are happy without documentation, there will always be those few never satisfied, always wanting more. And they will write it rather vigorously. Anyhow, open source community. My first encounter with WordPress was in September 2009. And my first contribution to its documentation was year and a half later on May 12, 2011. Besides many tutorials found online from the very beginning, I was using existing documentation to assist my reckless development in local environment. But then I found some features and behaviors in my local WordPress that weren't documented. What? And luckily I'm called my beer type of person, so I documented it. But it was easy to contribute in 2011. The first WordPress documentation, also known as Codex, was built on Wiki. Hi, picture time, sorry. And this has both good and bad sides. So this means that everyone with WordPress.org account can edit any page. All you need is this one account at WordPress.org, and there is even a history of every edit so you know exactly what happened and when. So if every member of community would contribute a little piece of documentation, we would build magnificent documentation in no time, right? When you think of it, Wiki does sound like a perfect tool for collaborating on open source documentation. The only problem with this is that anyone can edit any page. Can you imagine everyone with WordPress.org account, 12.7 million people being able to edit any page? Project grew, gained more attention and more spam. It's a maintenance nightmare. The solution was getting more control over who has access to it. So the tool had to be changed and really what's a better tool than the one we were building? WordPress. So the migration was set in motion. The first heavy load was differentiating end user documentation from developer documentation, making sort of catalogs and then start moving. And by moving, I mean copy pasting, manually. Several years later and many Google spreadsheets later, it was completed, almost. But by fixing this one problem, which is spam and unwanted edits, another problem was created. It wasn't easy to contribute anymore. And when it's not easy to contribute, people stop contributing, but not me. And I realized there was documentation I couldn't edit anymore. I dug deeper to find out who did this. And I found them, this group of people who call themselves WordPress documentation team and they were making all these decisions, how documentation is going to look like and who can edit it well. I like making decisions too. So I joined them in September 2016. So now, besides WordPress.org account, you need WordPress Slack account to communicate with documentation team. And then they might give you access to WordPress dashboard where documentation is created. And while we want to encourage people to contribute, we really want to be mindful of possible mistakes and spam that we wanted to prevent. So granting access is a fine line and definitely a bottleneck. But that's not all. This new workflow created a need for a place where people can report issues they find. These kinds of changes in community dynamics require the ability to scale to recognize the problem and flexibility to adapt quickly. All of which we didn't do for a long time. So now, besides WordPress.org account and WordPress Slack account, potential contributors needed to know where and how to report issues they found. And this is a good moment to introduce you to a different part of WordPress documentation. Now, the best thing you can do when leading the team, especially open source team, is to delegate responsibilities. So all of these projects that you're going to see have their own project leads or representatives. And they, because they are volunteering, have the ability to choose the tool they are the most comfortable with for managing their own projects. So we ended up with a different workflow for reporting and fixing issues for almost every project we have. Here we go. And user documentation, also called Help Hub internally, is located next to support forms where end user would go to ask for help. It is split in two parts, general and block editor and user documentation. There is no visible difference between the two, except that block editor articles will have change log at the bottom of the page. The real difference was behind the scene, the people who were maintaining and the tools they were using. But because they are on the same WordPress install, they do share some workflows and tools. So both of them, for both of them, content is created in Google documents because anyone can have access to it. And then it's pasted to WordPress editor. I know it's a workflow. Then we have a feedback text area at the bottom of every page for both of them. And this text area is intended to be used well for feedback, you know, for issues that you'll find on that article and report them. The problem is people use this for all kinds of purposes, including spam. And most of the time, people just report issues in our Slack channel. Now, block editor development is extremely fast compared to the rest of the WordPress release cycles are two weeks long. And this team is trying to follow that tempo. So they were using Google documents for collecting all the changes in the plugin and then trailer board to, you know, manage progress on documenting those changes. And because WordPress is using both GitHub and track, so SPM and Git for development and issue tracking, this team is spending a lot of time going through all those tickets and issues as well. Then we have developer documentation internally called Dev Hub. It is located at developer.wordpress.org and consists of eight different handbooks at this moment. But currently we are working on new one which is not published. It is called advanced administration. Out of these eight existing ones, five are maintained by documentation team and some are shared with other teams such as code reference, block editor and teams. And also advanced administration is shared with another team. So code reference is a very specific handbook because the large part of it is generated from the code itself. There is a script that after every release goes through all core files, collects every function, every hook, every class, and creates a page in WordPress for it. Still, this is only for PHP part of WordPress. We don't have this kind of documentation for JavaScript, which today is quite a lot. And the other parts of these pages that are not generated from the code are maintained from WordPress. So some parts are added by documentation team in dashboard and some other parts are added as comments, which are usually code examples added by community. So this is really a hybrid type and reporting issue for it. Here comes the fun part. It depends on which part of the page you found the issue. So if it's the part generated from the code, you would treat it as issue with the code and you would open track ticket. But if it's the other part managed from WordPress, then you would report issue in our Slack channel. And this is a great moment to ask yourself. If someone was just reading the page and found issue, how do they know which part is created where? And most importantly, why would they care? Right? Slack editor, also known as Gutenberg, is the newest bigger project in WordPress. And you can see that in tools that a team is using such as Webpack or Grunt, which can be found in older WordPress projects. But this documentation for this part is created in the same GitHub repository by markdown files. And then there is another script that goes through all those markdown files and generate WordPress pages for documentation. All the issues with documentation, everything is reported in the same GitHub repository. So everything is pretty much straightforward and clean. And the remaining pre-common APIs, themes and plugins are mostly managed the same way as end user documentation. So it's created in Google documents and then pasted in WordPress editor. And also issues were mostly reported in our Slack channel. And we do plan to add the same feedback text area there and, you know, hope for the best and maybe not have that much spam. And the latest one, Advanced Administration, which we share with hosting team. It is created in its own GitHub repository. So this is direction where we want to go. We are also using markdown files and we will use the same script block editor handbook is using to generate documentation from there. This is really useful for, you know, having a version control and knowing exactly who helped and how. And all management will be done in the same GitHub repository. And then we have contributor documentation. So every team that is making WordPress has their own blog and handbook. And all of this is located at make.wordpress.org. Each team is having regular meetings and blog is used for publishing agendas and summaries of those meetings and handbooks are used to explain what the team is working for, what the team is working on, who are members and how to get involved. So this is really a place for documenting contribution processes. And that's all documentation in WordPress. I know all of this, only because I have repeated this so many time to anyone who showed the slightest interest to get involved with documentation. And I was getting from them this face you're seeing, which is understandable. And when repetition became too much, we wrote it down in our handbook and recorded videos, but even then we've been getting feedback how frustrating it is to get involved with documentation team. So again, we had to rethink our tools, but with different set of criteria this time, the perfect tool. You guessed it, it doesn't exist yet, but here are some parameters to consider when choosing one. Ideally, people should be able to report issues on the spot without ever leaving a page or being requested to do something else like creating another account, searching through some other platform or reading guidelines, how to report issues. There are two types of contributors reporting issues. Those who report and just move along. And those who report and want to fix it. Those who just want to report it should never ever be aware of the workflow between the place where issues found and the place where issues fixed. And while we want to make it easy for people to just report issues, we don't want to make it difficult for people who are going to fix those issues. When issues are reported in Slack. That's additional work for our members because someone needs to make sure that report doesn't get lost in Slack noise either by fixing it right away or copying it somewhere else. Also, if the workflow or the tool is complicated, that's additional work for experienced member to explain to every new contributor. Unless you document your processes and keep that documentation up to date religiously. We all know that's not going to happen, right? And even then, if that happens, the tools and workflows should never be complicated. We are giving our free time to these projects, you know, it should be joy. And this one is really no brainer. Anything that you're going to do more than once, anything that can be automated should be automated. And open source projects have a lot of things that can be automated. When we talk about documentation, first thing is code reference. You want to automate that because honestly, writing that thing manually will destroy your weekends, all of that. And you will hate releases. But don't stop there. You can also automate generating your changelogs from your commit messages. But now you have to think about commit messages because fixing stuff won't do anymore. But don't stop there. Don't stop automating the end result. You can automate all your workflows. Every time you click a button, that's opportunity for chain of events, including sending enough, but not too many notifications. At the right time and right place about exactly what has to be done and where you see in WordPress project, which is very large. The most difficult thing is to be informed what other teams are doing and what is generally happening in community. I can hardly keep up with documentation team. And just recently we found out that the same workflows documentation team is doing also have other teams like learning team and marketing team and training team. They were all getting the same information the same way. So we were doubling and tripling the same work. That should be automated. And we were searching for a perfect tool to do all that. We couldn't find it. So we joined our efforts with those teams with marketing and training and learning. And we are making our wish list about the tool that will work for us. And we are in the process of building that tool for WordPress.org. Meanwhile, we decided to use one central place for reporting all documentation issues. And that is GitHub. So there are few arguments behind this decision, even though this is yet another account contributors need. We have removed the burden of having to know the workflow and how to report issues. All the other tools that we were using like Trello and Google spreadsheets are now replaced with GitHub issues and GitHub projects. And in the future, we hope to use custom integration with GitHub API, which will enable people to report issues on the spot. And then GitHub API will automatically create all the issues, label them and send all notifications necessary. Right now, we have two GitHub workflows in use. When issue is labeled, if the label is a WordPress version, then issue is automatically added to a project that is dedicated to documenting that version. So we are using GitHub actions for that. And another workflow is if the label is documentation project, so you see all of those projects. If it's documentation project, then GitHub bot is commenting on that issue, mentioning the project representative. So they know they have to go there and check what's there. So these are just the little steps, but we are getting somewhere. So in GitHub, people who want to fix issues don't have to decide beforehand what part of documentation they want to work with. They can just go to repository, go through issues and find what they like and start working on it. And in the future, we hope to move as much as possible documentation in GitHub. So then we would remove that maintenance bottleneck with granting access. We would just use the parser to generate everything. And we will have a nice and proper version control. We also want to offer documentation for different versions of WordPress. And that is also in progress right now. And in WordPress community, we like to give credit to all contributions, even the smallest one. But when that contribution is done in Slack by reporting issues and leaving a channel or just, you know, participating in discussion, it can be easy to miss some user names and don't thank them properly. With GitHub as a central place for reporting, discussing and assigning issues, we hope to finally be able to catch all contributions and all contributors and thank them properly. And when we talk about WordPress documentation, we cannot skip Gutenberg. This is a living example of how lack of proper documentation can slow down progress of open source project. For those of you who don't know, Gutenberg is a new editing experience in WordPress, not so new anymore, but it's still being avoided by many developers and site builders. At the beginning, it was replacing what you see is what you get editor. And right now, it is expanding to a full site editing experience. So what is the problem with Gutenberg? Gutenberg is based on React, but not just that. There is this PHP layer of WordPress, as we know it. And then there is React layer of Gutenberg base. But there is this mixed PHP and React layer, which is Gutenberg. In order to document it, we need people who understand all three layers in depth. But those people were rare and they were real developers. They were busy writing the code and no documentation. So we let Gutenberg be merged into core without documentation being properly adapted for PHP developers, which is majority of WordPress developers, or it was back then. And this resulted in frustrated users, obviously, who refused to use it. And, you know, when something is new in WordPress, it's a common practice. Someone will write the plug-in to undo the change. We are used to that. But this was much bigger. This resulted even in forking of pre-Gutenberg WordPress. And when you have this large change in code base and this strong rejection by your users, you inevitably create two streams. One stream keeps working on it because it's big. It's already there. So they try to make it better, more accessible, more attractive. They just keep working on it. But this other stream refused to use it. And they keep rejecting it because they have no place to learn from. They're seeing the progress being made every day. And they realize just how much behind they are each day. The frustration grows. Less and less people are capable of writing documentation for it. And then we face documentation depth. So how do you move from here? How do you fix this? Very slowly. However weird it may sound, the best documentation is written by those who are using it. And this is true for all documentation. Let people go through it and point to places where it stops making sense. Give them missing information. And if they're not too frustrated, they will feel the gaps. And you have converted the documentation user to the documentation writer. Congratulations. And you see, it's not perfect, far from it. WordPress as a project grew much faster than we even realized we needed to adapt. There was a time when different teams could do things separately, but for a while now we are seeing the necessity to communicate, to share the tools and workflows. And I think this state is partly due to our inertia. We join open source community, learn how to be a good member, and keep trying to make it work as it did before. It can be scary to propose something new to a project as large as WordPress. It's powering over 40% of the internet. And that is specific pressure to have in mind when you work on it. Not to mention how changes are slow, decisions are slow. The bigger project, the slower movement. Sometimes we need months to just make one decision that nobody cares about. So this is what the documentation team is doing in trying to move things forward. We had two projects selected for Google Season of Dogs project in 2020. And during this time we collaborated with two technical writers who helped us create the official documentation style guide and improve our end user documentation. Yeah, I already said we are working with other teams collaborating to build our perfect tool that will automate everything. And this might be strange to you, but for a long time documentation team was never involved in WordPress releases. We didn't even know who is doing documentation for WordPress releases. Yeah, I was loudly unhappy about that on Twitter. So I submitted my wish to be a documentation focus lead for 5.8 in order to learn the process and see how we can get the documentation team more involved. So in 5.8 I didn't change anything. I just saw what is the process and I was reporting to the documentation team what is happening in release and I was asking for volunteers and they responded. After that in 5.9 I was co-leading with another person and now we switched from Google spreadsheets to those shiny new GitHub projects. And this is really convenient because when you create a GitHub project under GitHub organization then you can add any issue, any pull request from any repository that belongs to that organization. You can add it to a project and you can even assign any person that is member of that organization. And I just kept reporting on progress in our weekly meetings. In 6.0 I was co-leading with two other persons and now we had meetings and we had plan, what to do and how. And we made mistakes so this was very important. We started making mistakes in Workflow so we can fix them later. And in 6.1 which was just released now last week we fixed some of those mistakes but we made even bigger ones and that was crucial. So now we are changing the workflow of documenting WordPress release. Some of the changes include regular documentation bug scraps. So that never happened in WordPress community and also we are switching responsibility of labeling issues and tickets to developers because developers can know in early stage of development if their code is going to be, is going to need any kind of documentation. And this one I'm really excited about. We are trying, we want to try new workflow where every developer working on new feature or any code would have dedicated documentarian who will follow along as questions, test code examples and have everything documented while it's being developed. So this is kind of grooming developer to start contributing with code but first understanding it enough to write documentation and we also want to stop releasing code that is not fully documented. Now this is one of those changes that will happen very slow. I proposed this more than a year ago and it was great feedback was great everybody welcomed it and nothing happened. So I started looking for a developer who is brave enough to work alongside me. And I found him in this last release. So we are going to try to do that in this new release to just do paired documenting and coding. And this should result in him being a better documentarian which is his wish. I didn't press on him anything. He wants to be a better documentarian and I will understand the process of contributing with code better. I will understand the code better so we hope to make this prototype work and always document your processes. That is extremely important because bus factor is real and it doesn't have to be that tragic like being hit by bus. You know people have been and they will leave open source projects for whatever reason and they have every right to do so. But let's make this the most important skill to have in open source project to enable others to replace you because transparency is the only way to keep open source alive. And keep in mind there is no documentation when things go south when project expands in this capacity and timeframe. We are the ones who have to make faster decisions. We are the ones who have to rethink our tools and workflows. We have to stop reacting and start leading the open source evolution and we are the ones who have to document all of this for the future. If you want to learn more about open source or documentation, I can highly recommend some of these resources. And if you are not already a member of WordPress community, I would like to invite you at make.wordpress.org. I personally always give cookies to documentation contributors. My name is Milana Tzap. I am a WordPress engineer at XWP, the loudest member of WordPress documentation team. And I'm also a classical musician. I know a little bit Italian from opera, but don't go hard on me. And if you want to discuss any of these things, you can find me on these resources. I hope you will find and embrace those inner documentarians of yours. And thank you very much for your time.