Why your documentation sucks (and how to fix it)

Hello, everyone, welcome to yet another Buddy webinar. Today we are going to talk about why your documentation sucks. And we'll try to fix it. I have a true expert when it comes to documentation together with me, I have Milana Cap with me, Milana tell us a few words about yourself.

Well, I'm a classical musician, by default by education. And I was also working as a classical musician for 10 years. Development was a fun hobby. And then it was more easy to live from development. So I switched. And documentation is probably my OCD, wanting to have everything structured. So I started with the workers documentation in 2011. And never stopped. So here we are. I'm right now WordPress engineer at XWP and one of WordPress documentation team representatives.

My name is Maciek Palmowski. I work here at Buddy as a WordPress ambassador, and I am your I hope favourite webinar host. So let's let's start with a small summary of what we learned today. So first of all, we will learn what does it mean to have a well well documented project, how to write and maintain documentation in a project? And what tools can we use to automate some parts of it. Also, remember, if you like what we are doing, don't forget to press the subscribe button on YouTube, you will be informed about all of our upcoming webinars, and you will have a chance to watch all of those that we recorded in more than a year already. Oh, and if you have any questions regarding the documentation don't hesitate. And ask in in the comments we will try to answer as more as possible in the q&a section in the end.

Okay, so let's start with what does it means? What does it mean to have well documented project? Because I think it's a bit more than just writing one or two comments inside of our PHP or js file?

Well, it's a lot, it's a lot more than people think. So if we take WordPress as an example, there is code reference. And that is one piece of the puzzle that is very important, but it doesn't tell you much when you start. And that's a huge problem to people when they start. So, next to code reference, you have to have some kind of tutorials and how tos. But also and there is specific system, how to write all that and how that should look and how to is not the same as tutorial or guide. And then there is manual. So how to use this software, and we have@wordpress.org. We have end user documentation. We have developer documentation, but more both of those are mostly what we would call manual just a explaining what is there and how to utilise, then you have, we have code reference, which is automated, which is the only way you should do code reference. And we have a new platform learn.wordpress.org or learning that wordpress.org. This is embarrassing. So it's probably well, it's either. And this platform is creating guides and tutorials and lesson plans. So all that is development. And also important thing is to note that as the software is never completed, the documentation is never completed. So everything is in process, more or less out of date. But those are different components of documentation. And also, there are other things like, when you have meeting agendas and meeting summaries, that's documenation. When you go to grocery and you have your shopping list, that's documentation when you have your little sticky note with, you know, things you have to do. That's documentation. So a lot of it is documentation and software documentation needs those four things. So it's manual, it's called reference is guides and how to.

Yeah, so it sounds a bit difficult, difficult to create difficult to maintain, just like that. It is it is right. Yeah, it is. Yeah, because I mean, this is one of the most often hear things against the project, that the documentation just sucks. It's out of date or something like this.

Yeah. But you will also hear developers like, oh, I don't write documentation, like I'm a developer, really. And you know, who has time for writing documentation. So nobody likes actually to write documentation. And that's why we have so many bad, badly documented projects.

And this is the thing I wanted to ask you about the self explanatory code, because this is quite often a thing that we can see hear that we don't have to write documenation our code is self explanatory.

I mean, that's a joke

I understand. I understand that there are some cases, especially when we started to using types in PHP. And for example, we have an I don't know like, Project ID, and we know that it's an integer. I mean, adding documentation that it's a project identification author, you think

the self self documented code is maybe you know, something that you can say, well, we have well documented code. So we don't need that much detailed code reference. But that's only code reference. If you take a look at code reference, it doesn't tell you where to put that code. It just tells you what it has what it returns, it doesn't tell you anything else. There is no context. So it is just a list a catalogue of functions and methods and classes that exist there. So it's not enough for, for a developer, you know, even today, after working as a developer for over a decade, I go, and some functions that I use for years, I'm not sure if I need post ID as a parameter, like, you know, when you have get the content or the content or, you know, get the title. It doesn't go like the excerpt doesn't go posted the post object or does it take anything? So those things are very simple. I know how to use that function. I know where to put it, but I just don't know, what is the order of parameters or what which parameters there are, but, you know, I don't I already have this knowledge, how to use it and where to put it. And that's something you don't get by looking at code reference. So, yeah, well documented code. well structured code. It's good. It's great. It will help you know, developers who come after useful, they don't want to kill you. And, and it will help you when you go back a few months later and you know, take a look at it. But I'm, I'm still not convinced that you shouldn't put some documentation in there as well. And besides that, you know, documentation about how to use this code.

Okay, yeah. So so just than that, it's always better to add a bit more documentation, rather than

not. Yeah, sure.

Okay, so how do you think that perfect flow? When you create a project and write the documentation to it should look like, should we first write the code and add the documentation later, or

that's never happened? We'll know. That's why

I have so many projects that that are waiting for this later.

But everything, everything we want to add later never happens, especially if it's not vital for product if the product is software. So what I'm trying to start@wordpress.org is to have a new workflow where developer would get dedicated the communitarian who would ask questions along the development process, you know, what is this? What do you put here? How do you use it and then create some code examples. And that's exactly how documentation should be written along the way while you are developing, you should document and you should think about things, not just code references, they said that should be automated, you should never think about code reference, it should always be up to date with the latest version. And that is not possible if you do it manually. So that has to be automated. But you should think about code examples, what are edge cases, how so those are the things that are specifically very much needed when you release the code. And that's something we have in WordPress releases. When we publish dev notes, that's where you will find how to use that. And that's very important. But I would really love to have that, you know, somewhere else, because dev notes are in blog, and then you lost it after several releases. So I would love to have a place where I can go and find all those examples that are really great. And those explanations, where you would use that function, how you would use it, what you can use it for, you know, all those things. And that should be done while developing. So when it's fresh when your function is completed, for now, you should have that documented. It doesn't need to be so when when you write code, and then you think, oh, no, I have to document No, you know, just put some items. It doesn't have to have nice words there. But it has to make sense for you. And you can then add or talk to the documentarian who knows how to add nice words. So this is also problem for developers. Like, I don't know how to write documentation. Well, you don't have to write everything by yourself, you know, just put items there, what's happening, how you do it, put code example. And then documentarian will, you know, wrap it up and make a nice structure of it, and then present it. So it should be done during development, and you should never ever release code that is not documented.

Yeah, so in short, write code. At least write some simple, simple sentences. What is happening, right?

Yeah, yeah. And if you do it every day, like one paragraph, this is it, you will see that after a while, you will have a nice page of everything documented.

Yeah, and just so overall, before the documentation should be a normal part of development, when we are releasing new code, if the documentation isn't finished, or it's incomplete, maybe even it's just incomplete. You can't release the code. It's not ready. Yeah, I understand. So we already talked about few But what are the most important practices when it comes to creating a good recommendation?

I don't think they're writing bars, I think I don't think there are practices it, it really depends on, on your audience on what you are documenting every project, if we are talking about open source, every project has their own way how to do things. And in open source, you know, people start doing what they know. So, in WordPress, we had a lot of change of tools and workflows, and you know, it's never ending. And while you're trying to figure things out, the software went out and you didn't document it. So those are things that depend on a lot of other things that have no connection to documenation itself. I guess the, the only way that I could say that is a very good practice, is the fact that best documentation is written by people who are using it. So that's kind of, you know, difficult to understand. If I'm going to use it, if I need that documentation, how can I write it? Because I don't know. I need documentation to understand what's happening. So this is like, going, uh, you know, making a bridge between people who know what's happening, and people who don't know, so they need to communicate. Because when people know what's happening, it's easy for them to just skip some very important parts. And we had that in Gutenberg documentation. Because it was initially written by react developers, and then we PHP developers, like, what? What's with this index js file? Where do I put it? And they're like, so it's your index js file, like, in React, you know what to do with that. So you have to, you know, talk to each other ask questions. When you don't know something, you have to ask question, those people who know, and they will realise just how much documentation is missing there. So this is something we always do with new contributors, when they express their desires, where they want to contribute, then we'll let them there and you know, try to make sense of it. And the first moment, you see no sense in documentation, that's your job, fill it up, you know, and ask the question, so we can find what what is the Core i, I'm so long in there that I don't see that much problems. But there are so many problems with with documentation in WordPress, with structure with everything. That's why we need fresh eyes. So that's, I think the the only thing I could say that is the best practice always having fresh eyes on documentation, especially from people who are using it.

Yeah, I fully agree with that's the problem with those project who are that are used by some group of users. They're just used to it. And they understand the syntax, they are just that they understand all the quirks because they added them. But every time when someone new tries to add something, become a contributor realise that it's not possible because she doesn't understand how it works or, and, and this is very important for for the team that they can either say, okay, you don't understand, go away, find a different project order can or they can benefit from learning that their documentation is lacking that people don't understand. And this may be the biggest problem that prevents the project from growing, because let's be honest, I could, I mean, I can't imagine using any big CMS because there is a difference between using a small library that I can just go through the code and Okay, I got it, I use this and this, okay, I get it I and using enormous project like a CMS because saying that there is a simple CMS No, that's not true. CMS will be always complicated will be always complicated. They can look simple. But underneath, a lot of thing happens. And without, and if we want to document it very well, there just, there just isn't a chance for anyone else to understand it. And thanks to this, just such a project will decline very quickly. Yeah, I mean,

that's what, that's exactly what was happening with Gutenberg, you know, people who understand it, they were writing the commutation up to one point, and then even they stopped writing it because they didn't have time. And the more project grew, and the more they went into development, it was, you know, less react, and more PHP and react. And now the less people know how to document it, and no one can start contributing, because you don't have documentation you don't know how to learn. So even today, I go to, when I need something to do with block editor, I, for my work, I go to source code, and just read how the Corps did it. That's not how you do it, you know, because maybe that's how you start writing documentation. But that's not how you use documentation when there is none. You go to code. And maybe that's not meant to be used that way in extending. So we have with WordPress, this, like how you write WordPress code, and how you extend it. And you don't write the same code in plugin as it is in WordPress, in core. So when I go and take a look at core, and I say, Okay, I will try to do it this way. It may be working, but maybe that's not meant to be done that way, maybe there's some filter that is not documented. And you get so frustrated by trying to make things work, you don't have time to get new ideas, to, you know, propose a new feature or new use case. And that's how you don't get any contributors. So we come to a point where good or bad documentation can make or break your project. And a lot of people just didn't use Gutenberg, because of this. And then you get no contributors. And then you only have people who work on it, and only they know how to use it. That's a bubble you don't want with open source. Especially with open sores that is built by this large community when just they refuse to use it.

Yeah, also, I would say, because I remember when I was reading about everything related to Dev Rel, and one of the things so all those depth relationships with how we try to connect developers with each other and, and one of the one of the things that are very important when it comes to DevOps is the passive part. And the passive part is nothing else than a well documented project. Because this is one of the things that most developers look at first, and I'm doing the same. One of the first things first, I look at the code to check, what was the last contribution is the project active? And the next step is, is there documentation? Are there examples and without it, I will probably look for for something else. And on the other hand, might adventure with WordPress started thanks to the documentation. Because it was it was great at the time. It was great. I think it was one of the best that at the time when I started using it was like 10 years ago. Yeah,

yeah. Well, exactly. There was a lot of it. So there's a difference. Not everything was very good. But there was a lot of it because it was on wiki so everybody could add it. But that's also the worst part of it because everybody could edit and that's why we moved to WordPress.

Yeah, and this is because this is also kind of interesting. Documentation, as we already mentioned, writing it is one of the dreadful things that developers do, they mostly don't like it. And for some reason you decided to, to have documentation as one of your most important things when it comes to your career. Why? Because

because this is the way to learn. So I'm purely selfishly in documentation, because I want to be informed about everything that is new, about how things are done in WordPress, how things should be done in WordPress. And, you know, when when you spend a lot of time there in documentation. So this was my hobby, I was, you know, having WordPress in local and just doing what I found in different tutorials, I build this Frankenstein in my local, and I was reading documentation because I wanted to see, this was just for myself, you know, to understand what's happening. And then I would find something in my local WordPress that wasn't documented, or it was wrong document. I mean, it was out of date. So I was like, what, so I had to fix that. And I fixed that. And then after a while, I was searching for something and found my own code example, in WordPress documentation. And then I said, Oh, this is my notebook to myself. So this is why I'm doing it to have everything when I need it. But also, in order to put it there, you know, when you try to write just one paragraph of documentation, you have to know like, a tonne. Behind it, you have to be certain what you're talking about, you have to know in depth, what is this function doing what it returns, you have to be certain in that. And then that's like, behind one paragraph, there's hours of testing. And, and that was really interesting to me. So I had to do some serious development, to be able to document and I was also able to do some serious development, because there was documentation. So this is the circle that just keeps me inside. You know, it's interesting to me, I guess. I'm not a gamer, but I guess that's how gamers feel like, you know, when they get to another stage and another so that this is my game, like, going in circles, learning something new, finding out something that is not documented, oh, my God, and I will be the first one to put it there. And then yes, you know, and then I will find it a couple of months later, and I will need it and other people will, you know, comment on that. And I would say, that's what I wrote. And I spend my whole weekend, you know, writing that and figuring it out. And that's something you never forget, like development you do. While writing documentation is something you don't forget, it's not like copy paste from, you know, StackOverflow. So it's just purely, you know, selfish to be better developer, and to be to know exactly what can be done with WordPress, you know, you cannot have that many projects, to know every piece of it. And I'm not saying I know every piece of it, but I know where to look. I know who to ask. And, you know, and a lot of it I know what's new, what's happening, where it goes. So I'm kind of having all those informations. And we all know information is power.

And so how would you? I mean, for example, how would you try to convince a person that thinks that documentation isn't needed in his project? How would you try to convince them start start doing it?

Well, I would suggest this person to find a way to offer this project to be used by other developers and just see the comments, see the feedback. So what you will get when you don't have documented project, you are actually only can only work with people who are just like you. Now there are developers who like to work with other developers who are just like them. Like knowing understanding the structure and the code, from the code, not needing anything, but that's a good way to not move anywhere, to have like minded people, and the diversity in backgrounds in way of thinking in experiences, and knowledge is exactly what makes the project good. So you get a lot of proposals, you get a lot of ideas, many of them are really not something you want to do, but you expand or you get a new idea for another project. And you get new contributors, you know, people you you cannot know, you cannot know everything, how to do good. But there are people who are very good in project management, there are good, there are people who are good in documentation, there are people who are good in different, you know, you cannot be just a developer and have successful project we all saw, that's not gonna work, you need a lot of other skills. And you don't have that, and it's completely okay not to have that, but you can have those skills with other people. And those people have to be different from you. And for them to be different from you. You know, you have to give everything you possibly can. So complete documenation, I, I would dare to say that documenation is equally important as code. Even though we don't have software without code, but we also don't have any movements in software, we document without documentation. So I would say they are equally important.

Yeah, that's true, because the lack of documentation is just like closed closing to your cold inside them inside of some walls, that

you and your buddies have a project

or only you are. Because you are the only person who understand what what is happening here. Probably after two or three months, no one, no one is because, but also there

is another. Another thing when you document, you actually, that is something what rubber ducking is, you know, you actually think through the project again, and you find bugs, I I've been finding bugs in my own code, while trying to document everything for clients, you know, to teach them how to use it, or when I record videos, how to use this functionality that I have built, so many bugs I found during that and fixed. And that's what makes you to really rethink everything. To get a better picture where you want this to go. When you just write code, it's so easy to stop creating issues to stop doing any of those things that make you stop and think. And you just throw the code there. And then somebody wants to help you and you say, oh, no, you know, don't don't do that, because I need to do that. So you actually do that just for yourself. You don't open your project to anyone else. And that's okay, if you want to have that project

just for yourself because that's perfectly okay. So, yeah, because this is I think this is also very important to say that while the code is crucial, because without the code, we won't have a project. But the one thing that you said about documentation that while writing it, you found some bugs I think that the another thing that is also equally useful are is writing tests. So writing tests and documentation together. Yeah, because as you said, this is this. Those are the rubber ducks those are those rubber ducks that will help you than that when you will start writing something it's like talking with with this doc or a friend because some some People life, or your kid, or your kid? Yeah. And thanks to this, we can find those bugs without even pushing it publicly, because while documenting, we will see that, okay, it's so hard to document. I think I know why. Because it's, um, it's written in a bad way, we created the code in a bad way. So it's hard to document. The same goes with test, if it's difficult to test your code, it means the code is probably written in a bad way, it should be fixed, it should be easier to make it testable. So we can also said that your code should be documentable because it's almost the same like like with testable code.

And tell me which which documentation from the project, you project you use you like, you see, as as one of the best review examples. If someone would like to learn those best practices of how the documentation should look like, where they should try to find

it, there is one example that I always go to. So gatsby.js has one page says, getting started. And I was on vacation. And everybody were it was 2019. Everybody was talking about Gatsby and how good it is and everything. And mind you I have never wrote a line of code in React before. So I was on holiday. And what do you do when you're a developer on holiday? You just, you know, you weigh all things. And I said, Okay, so I have time now I will check what this Gatsby is all about. And I went to their website. And you know, when when the website is leading you where to go, where to look, what are the steps that was beautiful. So I didn't have to, you know, look to really dig and find developer documentation. So there was the page getting started. And it just one pager. I started with having no idea what React code looks like. I did use a lot of terminal tools and CLI as before. So I know that part. It was new for me. But I started there. And at the end of the page, I had a working Gatsby application. And that's something beautiful. When you have this result right away, you have a working code right away after finishing what they meant to be completed. So code examples were amazing, so simple, but amazing. You get code example what you have to put there, then you get another code example. There is only one line different. It's highlighted. Hello, so you know where to look. And, you know, not too much in depth explanations just as much as you need to understand what's happening. So you have to have this understanding I had this app that I understand completely, I looked at code and I understand every line of it. But I didn't go through tonnes of documentation to read. They had links, like take a look here, if you want to learn more, take a look there. But everything I needed for this app to understand and to have it working. It was there. It wasn't like a lot of work. I don't know it was one hour or two hours, I don't know, something like that. It felt like you know, I was just playing with something and I had something built and that's what made me contribute to their documentation. So I did that as well and I read through all of it. So that is to me. Also another way of another form of documentation this one pagers that you get complete that is something similar to how to tutorial know, when you are focused on a specific problem how to solve this very specific problem. So that's not explaining in detail. And you know, guiding my, my knowledge and best practices is just how to do this that 123 10. And it's done. And that is probably the best documentation example I saw until that day. And after that, I see those jobs, JavaScript frameworks are really having a good documentation, very well explained and some even interactive as we were talking about that there's the next day. Yes. Yes, yes. Yeah, that. So JavaScript frameworks are really making this new trends in how to write documentation that will keep you occupied. And that will lead you where you should be going. So you don't have to really go and search. So we have that in WordPress, like you have to dig, to find you have to know exactly what you need to be able to find it that that's that's bad practice. That's very bad practice. But what we have in WordPress, is a lot of documentation, current documentation was just migrated from codecs. So it's a documentation all 15 years, 18 years. So, you know, we cannot really compare it and we are still struggling to make it more user friendly. But we are so long there, we need fresh eyes. So that's, you know, also the structure needs to be different. And that's another thing about documentation. You know, it's not just article, you're right, it's not a story, you write it, it needs structure. And that's when it gets difficult how you structure it and make templates of it. So that it's recognisable on every new page. So yeah, go back. Yeah, Gatsby was my Exactly.

Yeah. And one more question, because you have a chance to work with one of the biggest projects, there is WordPress? And what is the difference working on documentation? And in WordPress, compared to smaller ones? What are the biggest problems? And in managing such documentation?

I would say this fracture is how do you? How do you make this vast software? With a lot of things happening? How do you put it on one page? So the landing page for the commutation is how do you give users everything and not overwhelm them? How to how to know what what is the and how to actually categorise all that information? So the structure of it, you really need to have I don't know what is the word in English, the birds perspective of the whole project, that's very difficult to have, because it is big project. So you have to have this bird's eye view, but you also have to know the details how to structure every have that so can each part of it have templates, how to structure information. It's just thinking about it, you know, it's like, and and trying to put it all in one place where someone who comes first time can find everything and, you know, have lead them to exactly where they should go. It's just structuring it, it's very difficult.

Yeah. And in the end, I wanted to show everyone because you already mentioned that some parts of the documentation should be automated, like references and everything. And yes, our automated automation is the key and the cool part is it's not that difficult. It's not that difficult. I think that every every bigger language, every more popular language, has libraries that are responsible for our summation of documentation, I want to show what we can do using PHP Documenter. Because this is one of the of the standards in PHP. So let me share my screen. And, and, as you see, this is the result. This is a simple example that we got with PHP Documenter. And we got everything, we have everything. Divided by namespaces, we have all the packages, report everything. And, of course, no one would do it manually, we have all the constants we now with, with which file and which line, it's connected. And let's be honest, doing something like this manually. That's impossible. I mean, it is possible, but it took a lot of time. So if we check that our project, whole key is this, first of all this PHP, duck XML, and here we see where everything is built, what files are included, which are ignored. And if we look at the file, so for example, let's go into this src folder. Let's take a look at the delivery. We see the namespace, we see the commands, we see the count status, we see the comments for those counts, and everything. And if we will, just like I said, this is something very simple. We just need to instal PHP Documenter and run the command because every all the configuration is stored in our XML file. So if we will run it, as we will deploy it, it will generate all the reference references just like that. That's it. There is no there is no more magic. So generating references. Is that simple? And how how do you do it in WordPress?

We have. So I could share screen if you allow me. So here we have. Yeah. Okay. Okay. Yeah. So, if you take a look at WordPress, PHP, Doc parser. So this is a plugin. And you have here, in README file, you have kind of instructions what to do with it. This is what we use in developer documentation, helper, WordPress. Org reference. So all of this here, is sorry, everything you see here, is parsed with that plugin. This has a little bit different configuration, because it's using wordpress.org. And you know, it's getting code, or I don't know exactly if they're getting from SVN or GitHub, but it everything here you see, it's parsed from with this plugin, and so here is the name of the function description. That's all from code parameters, everything from code return, more information is created here in in WordPress. So this is the specific template that we have at wordpress dot work. And it's here Edit explanation that's how we added this. But source now we are back to code. Related info is also parsed from code used by description change log that is also from code and now we have user contributed notes which are comments. So you see this template is very specific, and it is built for wordpress.org. So it has different parts of it gets from code and different parts from wordpress.org. But there is also this one. So here reference for a EMP plugin. Again, classes methods hooks function was, and you will find here, the same thing. So this is just different styling, but it is the same thing. I could find some, okay, sorry. But you can take a look at that. And you can see how it was implemented here in this repository. It's amp project and WP. And here you, you can see docs. And that's how it was added and implemented. So there are a few examples how you can do it. And, of course, you can try for your plugin for your theme for your project, you can test it out, and if you get stuck, you know, just come to wordpress.org and talk to us. So we can, you know, find the things that are not working well that we can fix. So you can see here, like, when was this updated last time, and the build is failing. So this is kind of, you know, slippery, we are using it only when release is done. And then someone pressed the button, and it collects all the functions. And, you know, recreate the reference handbook. And that's it, we could use more work. So, you know, go there, test it, try it with your project, this should work with any project if you configure it properly. And then you can, you know, start working on it and maybe improving it. So that's, that's all I wanted to show.

Okay, so that's the last thing we have are the questions from the audience, because there are quite a few of them. So let's start with the one who, just before the webinar, How do you keep your documentation up to date when your app is constantly changing?

Well, we already kind of talked about it. So never release code that is not documented. If your app is constantly changing, then put an effort to document it while you develop. I mean, there is no easy answer. There is no like, formula or, you know, silver bullet for everything. You just maybe, maybe AI, that would be good. But you know, with ag always, as I said, reference code reference always should be automated. And, you know, if you have a good structure of documentation, then you can just add things here and there. But my advice would be never to release anything new until it's documented, even if that means, you know, postponing release, I wouldn't, I would just, I would just make it mandatory to, to not be able to release until the commutation is done.

Okay. So in short, if your app is constantly changing, constantly change your documentation, as simple as that.

Just Just understand that documentation is exactly as code never done. And if there's more code, new code, there's there has to be more new documentation is just

just that it's that simple, right. Now, let's go with a question from wallet. That what are some beginner friendly tools that you recommend for automating documentation?

Well, yeah, we already show I don't know if that's beginner friendly. But for our automating this, this one that you can look into different parsers if you have, if you want to play, you know, you can parse things from readme files or change logs, and then just, you know, add a few things here and there. Maybe you can parse commit messages. So if you write nice commit messages, and I'm used to write commit message like, what is the ticket number and what is the ticket title and then a nice paragraph what is done in this commit? So if you there are tools to parse Those commit messages. So you can create like, a really nice changelog that can be then parsed into some paragraphs and, you know, a nice dev note how to use things. So maybe that's something, I think parser is the key word, just, you know, parsing different forms of text.

Yeah, sorry, just search for name of the language plus, plus ultimately documentation or something like this. I did some small research before then you can find it to multiple languages, and most of them are quite simple. I mean, all the parsers are simple. You just have to run the command. The hard part is to write

the to be parsed. Yeah,

exactly. Because the parsers are really simple right here. Marco mentioned, the documentation is so important, and we can learn a lot from it. And that is that is true. From Adam, how would you connect a patient with documentation automatically, because annotation is easier to maintain? And more important to maintain because of type pens?

Well, with parsers, it's I guess, if there is no built parser, you should build one.

Yeah, I mean, this is this is the cool part about most of those libraries that they can be extended, you can change them to whatever you need, I mean, you can use the vanilla version. That's okay. It will, it will work, it will work. And for I think that, for most projects will be more than enough. But sometimes you have to add something, something more. So that's it, sometimes you just have to add something. And this is from Victor. In case of dogs, the target audience is very important. Dogs who are mixed audience is very hard to read for professionals and more professional.

Yeah, it is. But that's when you actually structure your documentation. What is for end user? What is for developer what is for? Well, that's what we have at WordPress, but there can be there can be documentation for project managers for there is documentation for people who are teaching how to use WordPress. And that's what training team is working. So, you know, writing for mixed for mixed audience is probably the first thing you should fix. You know, not don't do that. You write documentation for a specific audience. And make sure to have the right vocabulary, the right tone for that audience. And if it if you need to cover for another audience just played it, put it on a different place, and then use a different vocabulary there.

That's, that's true. Yes. I mean, I fully understand the problem. And also WordPress is a great example here, because it covers so much so many groups of people. Some of them are, let's say, code, just developers have some source of PHP or JavaScript doesn't count. That doesn't matter. And on the other hand, we have a lot of people who are no count, we have a lot of polyglots that are translators. We have people who are learning or teaching WordPress. And the recommendation has to be different.

But there is documentation for contributors. So how to contribute. So, you know, different audiences need to have their different places where they can read about.

Exactly, yeah, that's true. I mean, there is no chance for creating one recommendation for all it's just impossible. I mean, in a small project that is really doing just one thing. It's much easier to create such a universal documentation because it will be small. But when we are talking about bigger and bigger projects, We have to

take it from your own perspective, if you need to read to us this documentation, and you are, however small project is, when you see a short page, don't you just joy over that? And isn't it frustrating when you get to read something that doesn't concern you? You didn't come there to get that. So even if it's a small project, even if it's maybe easier, I would, again, say, split it for different audience types, just split it, put it in different place, and everybody will be much happier.

Yeah, yeah, that's that. The Ryan Walter mesh is one thing. The Gutenberg Project has a customer personal tool that can ingest documentation. So So to help with the answer of the previous question, and Molly is asking, that is good change. Look at the documentation.

Yes. Even bad change log is bad documentation. But change log is definitely the conversation. Yeah.

Oh, I fully agree. I mean, for me, change logs is always one of the most important docs when I'm using something for a longer time. And I want to see, well, what changed? Yeah. And there is nothing worse to see, especially on Android to market. Small changes. Cool. I. Yeah, bug fixes, bug fixes, small changes, or something like this. So sorry, yeah, this is this is really useless. Let's be honest. Okay, so I think we answered everything. So Milana, thank you so much. Also, at the start of the webinar, we started also a poll, do you document your code? And good news is that 65% said, Yes, we do. 34%? Well, I mean, for the fifth, probably, there is something.

So I would like to, I would like to invite those people who don't document their code, to come to documeantion team, and we will teach them how to document.

And this is really a great offer. And if you all are interested for me, just contact me, Alana. She is a really great teacher and a really fun one I can I can vouch for that. So so for sure. It won't, it won't be a boring class. And I can, like I said, I can vouch for it is. Exactly, that's true. And also, it's worth to mention that next week, in two weeks, two weeks, we will be having Freek Van Der Herten, who will help us to fix bugs in PHP using the Ray debugger. There will be well, a lot of debugging and it will be really cool and really interesting. Also, don't forget to join our meetup group called Buddy CI/CD group. It's a great place to get informed about incoming webinars. And if you like this webinar, don't forget to click subscribe on our YouTube channel. We'll also be informed about all the webinars, then there are some more interesting tutorials and videos. So it's a really great place to learn a bit about CI/CD. So Milana, thank you so much for explaining finger to about good and bad documentation. And it's an endless process. So this might not be the happiest for information people might learn from it, but that's true. That's true. And and yeah, so I hope that we will have a chance to do some some other webinar in some time. We'll we'll think about something. For sure. Right.

Thank you for having me. It was fun.

Thank you and thank you everyone for watching us. Have a great day. See ya.