 Where is Markler? Where is Markler? Markler... Markler... Markler... Markler... Markler... Markler... Markler... Okay, D.O.O., welcome to our conference, to that hall. My name is Irina. I'm a session chair in this room. If you have any organization questions, you can address them to me. I want to ask you about several things. If you see a red sign on the door, full, please don't enter. Or in another room. We don't have microphones in the room, so please respect these speakers and be quiet. Also, if you have any questions, please speak loud, because we don't have microphones. When you enter or out, please close the door gently, okay? And we will have a short break from 12.10 to 12.20, okay? Please be in time. Okay. I'll be about to start. The next was shot prepared by our Bruno documentation team. It's about no documentation, no comments. Yeah, let's welcome the speakers. A handout, which is a copy of the play portion of our presentation. If not, do we have any more copies? No. Okay. If you don't have one, find someone to sit next to who has one and look on her shoulder. Okay? Here's an extra copy. Does anybody need one? That's fine. We don't need to do a spoiler. And I'm the Beatlebar. We hope that all of you are comfortable. For we will show you how brilliance alone can make wonders from but dirt and stone. But? That it takes skill to make that push. And what you also need is... Push! Now, play whose characters bear some likeness to those with the real world cares. Can you guess the role's portrayed? Can you rest the veil away? The queen! I have music and I sing in a band. Now, my good people hear me. I just come up with a decree. I command that only on open field, for me a castle swiftly be built. By five p.m. sharp, with many a room, else my minions are facing their doom. The architect. I'm the ardent architect, shaper of dust, silicone plastic and fragments of rust. I can craft it with closed eyes. My teams, they don't strum and do realize. The page. I'm the proper page art in motion, dynamic, discreet, deep as the ocean. To go to the castle, the queen needs a map. To know where to go for a nap and where to go for a crab. About castles, not much do I know. I will do my best at the map, though. Feast your eyes upon how it's done with but utmost skill in our act one. A castle raised, I can craft it with closed eyes. My teams, they don't strum and do realize. But seriously, just a few hours left, if I fail my head, my body, bereft. About castles, not much do I know. I'll do my best at the map, though. But seriously, just a few hours left, if I fail my head, my body, bereft. The architect ponders. Two wings or three. More is always better, surely all can agree. The steam begins to whirl, the dust begins to swirl. Let's have some wings, feels the air, oh what industry. The page appears through the dust but finds no comprehension. So he does what is natural. And without any pretension he googles the word wings, finds them paired on most things and draws a map to a two-winged mansion. By now it's mid-morning and time for a coffee break. The page grabs the architect. They chat in the coffee table. So the wing count is actually three. Isn't that obvious to see? The page just nods as his hands begin to shake. And so the day progresses. How fast the clocks fly. The page struggles mightily to learn how, what and why. Changes went furiously. Strangers turned furiously. Frustration marks the pages' step once deft and spry. Now castle seams raised. Hard to see in the dusty haze. The map seems drawn, judging from the pages' days. The clocks chime five. Trumpets sung live. The queen then arrives. She's quickly irate. Because nobody knows how to open the gate. But when her leg gets in the desperate stock, as she looks for her throne, she goes... What the fuck? I need to pray for the neighboring king, who to this castle will come visiting. But the info on how the drawbridge to set is updated so the poor king goes flat. So the queen puts her foot down and says... This may sound cool, guards off with their heads. Reference were great, so he don't present my wisdom now. Now, I will not retrieve these morsels stationally. Realize that, in this endeavor, your life is eased when you work together. Swiftly be built. By five p.m. sharp, with many a room, else my minions, they are facing their doom. But working together in our act too. A castle raised, I can craft it with closed eyes. My teams, they don't strum and do realize. Yeah, now it occurs to me that with the page, we should make sure to be on the same page. About castles, I know not other much, so with the builders, I will keep in touch. But seriously, just a few hours left if we fail our heads, our bodies, bereft. Hmm, two wings or three. And more is always better, I surely all can agree. He founders their laws. Ideas that's less wacky. Designs that's less hacky. He avoids rework, and then those time-sucking malls. Now, castle indeed raised. No more dust in the breezy air. The map is indeed wrong. Detail, so she says. This is great. Finally she becomes happy with her new layer. This item just, folks, let's hold the fan. I acted to present themselves. We don't have microphones, so I guess you guys will pick one. Yeah, so I'm the quick tempered queen, right? No, I'm Vara, I work at Red Head, and I write documentation for Red Head Self Storage, and I really like it, so that's me. Hi, I'm Clayton, and I write installation delayed. That's it. Hi, I'm Marek, and I'm doing basically anything middle-backed. So middle-backed dogs, I'm your guy. I'm Irka, I write mostly for platform virtualization, and I'm also the resident crazy cat person. Hi, I'm Tinti, I write for OpenShift, and I'm also responsible for the rest of this presentation. So here's what's going to happen next. This is a workshop in theory, so we're going to work, and this means we are going to talk, this means you are going to talk, this means we're going to talk together. What are we going to talk about? We have three things. First of all, we just presented a play. This is an extended metaphor, so what we're going to do is first unravel it. What does it mean? What does it mean to you? What does it mean to us? I think we use language in the play that perhaps is a little bit difficult to understand, and perhaps the metaphors were not clear, so let's talk about that first. Then after that, we'll touch on what is no docs, no commit, slash merge, which is the title of this presentation, and after that we'll discuss if we have anything else to discuss, we'll discuss. What do you mean there will be a break, as Edina said, at school? So that would be a good time to escape and get some lunch, and stay away if you don't want to. Come back, okay? No obligation. Okay, so let's talk about the play. In the beginning of the play, I think on line 15, if you consult your script, then there's a question, right? The Beatsley Bar hosts a question. Can you, what did we say? Can you guess the roles portrayed and can you rest the veil away? The roles portrayed. So the three primary roles here were the architect and the page. So these are obviously somehow related to no docs, no commit, right? What do you think? Anybody volunteer or guess? What are those roles? What are the analogies in terms of real world? Okay, we have... The queen is the customer? Oh, damn, yes. This is great because we're really clear about it. You know, architect is architect. So French is the programmer? Oh, okay, that's very close. What does the page produce in our play? The page produces... It's a map. He's got to be thinking the right... Oh, yeah! That's the power point in the room. It's right here. Okay, and then, so what is the architect then? It would be the developer, right? So let's see, we have the queen page architect, customer, technical writer, developer. Let's go back and forth so that you can kind of get that into your head, right? Go back, go forward, okay? So these are the main metaphors for this. And now we're going to go forward and think about the other metaphors, okay? What else is... What else? What does the fairy food... What did she... What did you say? That's interesting to have already a life disease when you work together. Yes. So working together is what she said. What did she do? Yes. She's the manager. Well, yeah, I guess in some sense. She is the manager. She is my peer. So, yeah. She represents the wisdom of working together because oftentimes... What did the weekly bar say initially? The weekly bar. What did you say initially? What was your premise in terms of like... Right, so a small play whose character is bad, someone like Mr. Do's would agree with those guys. Right, but before that... Before that... Right, of course. So, firstly, my premise was that it takes skill to make that push for the figurative and literal. And that brilliance alone can create wonders. Right, so basically we have an idea that... And this is kind of a myth that's supported in society is that you can be brilliant, you can have talent, and you can... The lone guy, hacker in the basement or in the garage or wherever can create a new Bill Gates... There's a lot of individualism and this kind of thing is a very strong underlying message that the wisdom of the fairy foo who is perhaps a manager or perhaps somebody who has experience having people work together, which is I guess a manager, corrects by giving the architect and the page a means of communication. Right, so the communication and structuring the communication is important and that's what the fairy foo is. Okay, other metaphors, let's see. Other... Let's just turn the page and say was there anything not clear in the... We try to use really fancy language. Is there anything that you don't understand, you want clarified? What for? Yeah, exactly. It's like Yahoo, but, you know... Yeah, but cleaner, you know. Other people let you put the used... The divine things. There's a drive-in back there. I think it was called line-breaking for me. Okay, alternative stuff, okay. I was there. Alright, so other questions? Let's see. Anything particular or anything? Okay, so what you're telling me is the play was completely clear, everything was perfect and you just want me to continue to get on with it, right? Alright. So we did really good job, right? Yeah, we did a good job. Okay, alright. Let's now turn to... Because, yeah, let's turn to the next slide which is what is technical writing? Because documentation is technical writing and so here, we ask people in the audience, that's you, to tell us what is technical writing? And we're gonna do this... We're gonna get some answers, so we're not gonna... So... Now's the time to raise your hand and say something. And next slide, please. This is in your experience. IME is in my experience and my H-O is in my humble opinion. Okay, so then really, what do you think about technical writing? What do you think about what technical writers do? The template for this is that you say, Hi, I'm brave. I'm going to say my role. I am a blah, blah, blah. And this is what I think, okay? So, yeah, I know this guy's groaning because... It's time when I kind of remember that intro. Yeah, you remember. You want to start? You started. You raise your hand. Hi, my name's Anton, I'm a software engineer. So I'm sort of in the middle of making customers and being an engineer, you know? And in my humble opinion, technical writing is an ongoing practice to get some meaningful information from the engineers and put them in some understanding form for general audience. Okay, thank you. So, I take it you have an intermediary role and the keyword that I heard from you was it's a struggle. Right? I was three years, yes. Okay, that's in your experience also. To get information from the engineers into some form that... It's easily understandable because, you know, reading GitHub source code is not so easy to understand. Yeah, yeah. I've tried that. My hair used to be smooth. The source code was smooth. Okay, so that's one. Okay, let's get at least five. I'm not going to go forward until we get at least five people. Okay, we have one. Hi, my name is Tuanpe. So I heard, because my hair is also bad, I don't know what that is. I heard I'm QD and technical writing is this the part that I need to get to. Okay, thank you. My name is Tuanpe. So, basically, in my opinion, it's great, like, prescription of the product of some stuff. But the person who does it should have to acknowledge about this product. So it's not kind of like... So you can find the documentation somewhere in the description, but with knowledge from the site. Okay, so if I understand correctly, you say it is writing that is done by someone who knows about the product. That's the main thing, because it should be in the areas of the product. And it encompasses documentation, but not just on the model. Other things. Yeah. Excellent. Okay, that's two. Ready to go? Okay, turn the back. Hi, I'm David. I work at SUSE as a QA maintenance engineer. And I'm also a little bit involved in automation. And I agree with what you said. Sorry, I didn't hear your name. But on the other hand, I have to say that if you know too much of the product, you do not see exactly what the user would like to know or see written in the document. So actually, there must be some kind of compromise or some pair of other IS that can look at the product or whatever we're talking about from a different perspective. So yes, technical knowledge, but it's very important to have some other point of view close with the user. Okay. So if I can surmise, then I didn't catch your role. What is your role? I'm a QA engineer. QA engineer. Well, as soon as we have two teams, so I'm in the main team. Okay. So you're this kind and there's another kind. But in general, QA is what it is. Okay. And you say that it is possible to have an extreme knowledge, like too close, like if you know it so much, then it's really damaging in terms of not presenting something balanced towards the customer. You need somebody else to kind of mediate that to soften it up. Did I catch what you were trying to say? More or less? Yes. That's the point. Okay. Thank you. That's it. Anybody else? The side of the room is over-represented, I don't know. There's the PowerPoint in the middle and from the front. Hi, I'm Stephen. And yes, I work in content services right now and I'm a weaver. A very clever, actually. I try to bridge gaps. And my notion about technical writing is that it's bringing order to chaos. Bringing order to chaos. And that's really a simple idea. Okay. Yes. There we go. That's very straight. If I can summarize it. Try to get a few more words. Wait a minute, I have to do this. I'm being rigorous, okay? I have to do this. I say, you are a bridge-builder. Bridge-builder. You said weaver. Bridge-weaver. Bridge made of weavings. So, a bridge-builder slash weaver and you think that technical writing is bringing order to chaos. Okay. Okay, great. Well, bringing order to chaos. That's really, okay, interesting. We'll talk about that. We'll have some beers. We'll have some beers. Yes, please. My name is Sean. I agree with everything Stephen said, but I'm going to say it's smart. He likes to follow in it. I work in the documentation discipline, but strictly with upstream open source projects and helping volunteers. And in my opinion, which is not at all humble, technical writing is about taking a large amount of information, a huge wealth of information, a grain dump from your engineer. Is it chaos? And organizing it, strategizing how it's presented and making it so that users can quickly and easily find the piece of information they want. Okay. So, to summarize, you also work in content services. I do not. I'm just like hearing echoes of this. It's because of your beer, man. I only pretend that I'm a beer. Someday. Someday, I'll say. Okay, whatever you do. I thought so rigorous, but whatever you bring order to chaos, but with the specific intent to make it easy to find for the customer what they're going to do. So there's an additional layer of intent. Is it isomerized? As an Austrian person, I'm not a user of the customer. Okay, user of the word. Right. Well, whoever would, this is another controversial word, consume the documentation. This is, basically, you want to make it easy and effective and quick for them to find it. So, this is finding it. Okay. Great. So then we have a bunch of opinions. Like, I know we did find, so the back row is like saying, okay, let's move on, but does nobody want to represent the back here? The mask? No. Okay. Interesting. So, you didn't state your role, but I think it would be developer. Would that be fair to say? Okay. This is just offline knowledge that I happen to know. But you raised the point, you didn't say what you think technical writing is, but you said you mentioned a problem of technical writing, or one thing that you see is that when writing about it, then without the knowledge of the product, actually using it, right, hands-on experience, experience gives you something concrete to express. Like, if I were to say, if I were to write a poem, what's it like to be blonde, or something like that, then I had no experience in there, so I couldn't really feel it. But if I write another poem, like what's it like to have nothing to say on stage, then I'm not allowed to. Okay. Great. So experience, that is a, and it could be a problem, because nothing meets experience, right? Okay. Good. So... Oh, are you raising your hand? No, you already spoke. Oh, hello. In my team, they work with most of the customers back there. They're extremely impressive. The enterprise architects are extremely impressive in cutting-edge technology, so they want to open a stack, they want to open a shift. It's super exciting for them, but they say, do you know what? We're not going to invest in any of the proper support services. We do that straight from the documentation. We're clever people, let's do it. And then they open tickets and say, do you know how in these cases I'm not documented? Can you explain to us how you set this up? Can you figure that? We are a bank, but actually the security requirements that we have, they're not really documented in there. So how did you get guys inspired? And that's what my take is on technical writing. It's a fine balance. The need to work there, I think, is really difficult when we don't get the feedback the customers say, can we get a lot of XYZ and a bank on shopping, a possible public organization? How can we get these details from the guys, right? Can we go upstream? Can we directly work with the developers? Is that how we're going to help us? How does it work? So if I'm an SMI, I think your role is in the support organization, one of the three bosses is there, and for you technical writing involves, similar to what you were saying, is more than just documentation and that it's specifically things that the customer looks is to use cases, use perhaps dynas or reference architectures, it involves perhaps things that are not strictly in the classical world. Did I capture what you just said? Okay. Great. So we probably are out of time, right? What's the next slide? Okay, so the next slide is we're going to go into the actual no docs, no commit philosophy. Okay. So why don't we break early so that we get 15 minutes of time to decide to not come back if you don't want to? But also to get more food, because I think there's a lot of free food here. Please go out and enjoy yourself. We will reconvene at 12... Before we do that, you have a bunch of flash sticks here with the script and the slides, so if you're registered, you can find them along, and for those, if there are more people than the flash sticks, just copy them in 15 years. This is a script. If you have hard copy, then you want a soft copy and the slides, like this. So in 15 minutes it'll be 12.20, right? Yes, please return to the room in time, 12.20, okay? Use the break to wrap your pocket and also leave the feedback about the presentation. The links you will find come to the back side of your program. Okay. Ooh! I really recommend this. Thank you. Let's see. Would you see your next case with documentation? Because when you're hacking, you're going to do your documents. And you don't say, should I do this or that? It's your take. Thank you. Thank you. Thank you. Thank you. I agree with this. In fact, I felt they were up. The rule of thumb is at least for me, like, you know, for me, these questions, like, how do you see yourself in five years? How do you see yourself reading your code in five years? Something like that. So that usually works for me, but only for me, that's the point. Yeah. A lot of yes stuff. Yeah. Thank you. Thank you. Thank you. We're going to be done. I took it from my side. I was looking at this, and I was more thinking about specifications than the documentation. In my experience, I had the most problems with the specifications. Let's see, that's the point. That's the point. That's the point. That's the point. That's the point. That's the point. That's the point. That's the point. That's the point. That's the location. That's that, that's what they say. I want to expand, yeah, because I have a lot of preparations, I have to go very much to this building. I'm going to come down for a few days, so yeah. Actually, I'm going to try it out. Yeah, I'll come back. Of course. I'd like you guys to go. Yeah, yeah. So we can talk about roots in the presentation. Yeah, we can talk about it as a whole. Yeah, it's presentation to the workshop. The floor is pretty clean. Yeah, I'm going to go up. Yeah, I'm going to go down. Yeah, I'll come back. Yeah, yeah. I'll come back. Okay. Yeah, yeah. I'm going to go down. Yeah. Yeah, yeah. Okay. Yeah, yeah. Let's see, let's see, let's see, let's see, let's see. I'm still working on this next one, guys, but for sale. Basically, just do it, don't check what's going on. It's like one thing to do. That's also with the crossbones underneath. Okay. What is this? Okay, so we have one more time to kill. Let's finish this, what is technical writing? Which is not this thing. Magically. Now we're going to go fast forward, right? By the way, anything about the play? You can always talk to us afterwards. Okay, so the next step. Slightly before we get to this, I want to open the same question. What is technical writing in my opinion or in my experience to some of the people on stage? If you want to say something about that, or Robert, then please. So I would say, I mean, I agree with everything that was said in this room. And I think that technical writing is about getting the information and understanding the things, right? It's really a really understanding. It's a sign, I don't feel like it sometimes looks like we didn't try to understand it. Trust me, we are trying all the time. But for an understanding, we need to have a developer on our side to... Because sometimes we do have questions, right? And we are trying to understand it, so that's the thing. Okay, and what else? Want to say something? Yeah, I thought a lot of people said about, you know, we should try talking about how we need to tell the customer what it needs to hear. Tell them the things that are interesting. And I think that's a really good point. And in a lot of ways, we're kind of like an intermediary between the software and the people that develop it and the customers. And so, yeah, we have to pay attention to what they want to hear. And so I get that information and come back to the bridge. We are basically like playing in the centers, right? We need to collect information from global software, for example, and for customers if we have a chance to talk to some of the developers from quality engineering, right? Because they also have another point of view on the product. So we have to somehow wrap this all up and then produce them up under the recommendation. I once used a metaphor for us, because it's slightly controversial, that we are sort of like Moses. Because he has to take the infinitely complex word of the divine powers. They're all over us. Why are they all over us? Because we need their help. And he has to condense it and simplify it into something that is comprehensible, yet followed by normal people, not normal-ish people. Now we're actually in front of it. As far as businesses advance, are normal people? Oh, man, okay. You shouldn't have asked that one. All I can say is we're not professionals. That is, we're not professional actors. So everything expressed here is sincere. All right. So this leads us, actually, these kinds of things like the friction or the difficulty in avoiding to lose our heads, right? I mean, what is the end of Act 1, what happened? What was the consequence before the rewind? The minions lost their heads. The queen was irate. The king was dead. The king was dead, yeah. Who cares about the king, right? It's the queen that counts. Okay, yeah. The king was dead. There was a bad experience. So the point is these things were avoided in the second act due to a better communication model, basically. And so this is the focus of this talk, actually. What we're going to do now is pass on to step or to do item number two is Grock. Who doesn't know what Grock means? Okay. Can you explain what Grock means, please? Yes. Oh, can you explain? Grock turned forward from the Robert Heinlein novel, science fiction novel, and he needs to understand. By Grock, I understand. Well, it means understanding its abilities, profound sense. Understand everything. Right, right. Be essence. Okay. Okay. Oh. What does an English say then? You know, some people heard accurately. You know, some people heard accurately. Yeah, I had to squish it all on the slide and make it big and, you know, fulfill, you know... I said in a good document, if you should explain the... Right. This is not a good document. We should use slash. It's all caps. It's all caps. It's like... And patterns, isn't this in the running toast? What? It's all wrong. Is that the rule? So this completely violated the style guide, but, you know... I had to do it. We were just showing you guys what we were involved with, right? Mine and Grock's were like this. Right. This good point is that it's concise, right? And I think by the end of this talk, then I hope that the people who are developers and who would like to help their documentation effort realize that a small, concise note can be helpful as the seed, right? But we'll get to that in a few seconds. So we're going to understand no docs, no commit, slash merge. But here we have no something, no something, okay? This is a pattern. What does it mean? Have you ever heard of this no food or drink, no party? No clubasta, no party? That's got to be pretty common here, right? Nobody has heard of that? I had to do it from you. Come on, this is like... Or, you know, many commercials have this. Advertisements, no compari, no party. Okay, maybe this is just Italy. Okay. No worth... Yeah, exactly. This is the same idea. What is saying the idea expresses is that without this important thing, then you cannot have the next one, right? It's like a gating factor. So, let's see. Next slide. What is party here? Party is quality. It's like, without that kind of food or drink, you can't have a quality experience, right? And so here, the documentation, including the user cases, including the readme files, including, you know, just the man pages, all these things all are observed and read and contribute to the quality of the user experience. In this case, the user is the customer. And what we're trying to do is increase that overall experience, right? We're trying to get to quality. We're trying to make quality to be apparent. Because quality is not something that can be really inherent in something. If I say, does this have quality, this pad of paper or this pad of sticky notes, does it have quality? For some people might say yes. Some people might say no. And the real answer is why would it have quality? And who says, for me it has quality because it's green. I like this color. And it calms me. So, to me it has quality. And that's just right now because I'm nervous on stage. But maybe another day I'll be like, oh, I don't need this. It's just dead trees. What a waste of resources. This has low quality. So quality is in the perception. And what we're talking about is the customer perception of not just the documentation, not just all the things that they read, but of the product, right? They use the product. I mean, really, we're talking about software. What is it physically, tangibly that the customer sees or feels with software? There's a keyboard. There's a screen. There's, you know, the software is all inside. Everything is in their experience and the documentation. And how it interacts with software is all about the experience. So quality comes from the experience. Quality is the moment of experience, according to this really old guy who's probably dead by now, Robert M. Piersig. Anybody hear of this author? Robert M. Piersig. Okay, he wrote a book called Zen and the Art of Motorcycle Maintenance. Okay. It's about quality. It's an inquiry into the qualities. Okay. So quality is the goal here, but we can't build it into it. So, but how do we get to it? We have to act in a way that fosters it. Okay. So next slide. So we have some QA people here, QE in some. Okay. So what's the difference between QA and QE? Who knows? Okay. But the main thing is the Q, right? The Q is the quality. Quality, something. But there's quality involved, right? So what do you come in? Act right. We've got QE guys here. Raise your hands. The difference is smaller. Yeah. Thanks. Okay. You should join the docs team, I think. We made these fun decisions. Okay. In this community, which is also concerned with quality, then there's this philosophy. Okay. No test, no commit. What does this mean? Who can QE guys, QA guys? What is no test, no commit? Tell me. Okay. So basically it's a gate on accepting of changes in the functionality. And that gate is in the form of a test, right? No test, no proof of non-regression or non-breakage or proper integration, then no commit, right? So basically it's saying we can't really express quality. The one way that we know how to express quality is to say, we don't want to break things, okay? Or we want to make things. And we will not step forward until we have the assurance and the engineering of a test. A test gives us this kind of thing. So by doing this, we don't know if really we can add quality, but we know that we're maintaining it, right? By doing this process. Okay. So same idea. Let's go. What's the difference? It's more than one letter at this time, right? There's one word, no docs, no commit. This is because now we're thinking, okay, before I commit, before I make this change, I as a programmer or developer in the common parlance, I am thinking not only of the functionality, not only that I don't want to break things, but I'm thinking of the user or the customer or the client. It's like I'm changing, for example, I changed the output format on the bin list command, right? I remember long time ago, bin lists used to have a fixed width format. That is, when you say list LS minus L, you get fixed number of columns for each field, for example. And this was really problematic for usernames, because my username was, or login name is TTN, which is short, so there's like lots of space that's wasted, right? If you look at bin list output, you see that these days, if you do a bin list minus L, then if all the columns are of one width, then they're compressed, right? So this is a change in the output format of the LS command. So whoever did that, it was a GNU hacker, because this is GNU core utility. At that point, they documented it, okay? So they were doing this, they were saying, okay, I'm going to make a change in the output format. This is something that will affect the user. I'm going to document it because I want the documentation, how the user perceives my program, to be in sync, to be synchronized without the reality, how it actually behaves, right? So in this way, I maintain the quality of the program. So that's the idea of having a synchronized thing, and the communication style helps a lot with that. Okay, so this is, when it's one guy, it's very easy, because it just takes the right mentality. Just think, okay, well, I have some pride in the output, I have the pride in the user experience, I want them to be synchronized. It's all one guy. But when there's more than one person, when there's a docs team, and there's the developing team, and there's the QE team, then how can they maintain quality if they don't communicate, right? That's basically what we're saying here. So next slide, please. So that's the gist of this presentation, is like, how applicable is this philosophy though, right? And why is there no docs, no commit slash merge? I mean, what's up? Besides violating style guides, why is there this? If I take, like, when you're committing to, you're changing the software, and every single change, if you submit a small blurb to the docs team and say, okay, you know, I change this, I change that, then maybe that's too granular, in fact. I would say most people kind of think that's the first reaction we get. It's like, okay, you want me to inform you I'm the programmer or developer. You want me to inform you of everything that I do? And it's like, well, I just, you know, changed a little typo here, or I just changed the white space or added comments. Like, I don't need to inform you of that. And I agree, I think that's too granular, right? Because that's not something that would affect the user. The user or the client or the customer doesn't see these things. So if I take a strict stance like, okay, I'm going to improve my organization and we're going to make all the programmers, every commit they're going to do something with docs related. That's too granular. Okay, next step, next slide. And if you do no docs, no merge, which means, okay, on every merge, so I do a bunch of commits, do my rebasing, blah, blah, blah. And now it's time to merge the feature into the mainline. If I do that, then maybe it's too coarse, right? There's a lot of documentation that could be affected by that one. So obviously, if one is too granular and the other is too coarse, you have to do the next one, right? You have to choose at runtime. Next slide, which would be commit or merge. It depends, right? That's why it depends. You have to think about what is the impact, the client impact, the customer impact, the end user impact. So at this point, people are going to escape. Bye. Please send me back. So it is, I think it is not the intent of this talk to say no docs, no commit. It's not the intent of this presentation to say no docs, no merge. But it's to encourage the thinking of when I do a change, does it affect the user, the end user, the client? The customer, or even myself, because oftentimes I'm going to be writing software for myself that I'm going to be using in six months. And I add a cool new option, and I start to use it immediately, but I forget about that option. And then in six months, I'm cursing up a storm because I think I hit the same use case. I want to add that option again. I have to go and look at the source. Wow, I could have saved myself three hours of digging around if I had just written a little bit of documentation in a read me file that explains this new option. But the point here is that commits to granular, merging perhaps to course, it should be together. And when you have a team, separate teams, then this togetherness has to be, should be. This is what we hold here. It should be part of the system of the organization. That is, there should be some kind of, let's work together to add this feature. Let's work together, inform. So there's the planning, at the planning stage, then things to get started. Excuse me one second. Can someone else talk for a bit? How about you? You have an experience in your work so currently. I have two comments. The first is probably the most, the closing of the last thing we were talking about. So there's some provision control made to auto-document the changes so that eventually a documentation team can look into the component, the log, and try to understand what's changed without the developer needing to talk to the documentation team. Well, it would be, I think, in the ideal world. But in our work, we usually work on several products. And there are many documentation backwards for things to be documented, for example. To be honest, there's no time to search revision history for every product. For example, in Red, Red is basically a bunch of packages all together. So looking into the revision history, it takes that much amount of time to dig into it. It's easier if you are a developer. And also, sometimes, we are not able to tell, okay, is this change that's significant that we should include it? This is also, for example, problem with the release notes, right? Because sometimes you just don't know which change is that huge or not. Or which is just how the customers use it. Because the knowledge of the product is so complex. So we count every time to do that. But, yeah, basically, you're right. It would be great. But it's better to, you know, as the... I was here because I think the comments on the... As for developers, as for the developers, it's not an application number anymore. When I write an incoming message, it's used for the developer that we want to know why that change on the course of the communication. So I think there's a separation there. I mean, for example, sorry. Just a comment for that. I was working on set release notes for the last release we had. And basically, my... Because I was new to the team, I told you, okay, so just look at the upstream release notes. And the upstream release note is going to just a bunch of give-offs. And I... And, you know, set this a little... It's kind of complex, right? And so I was lost. I was really lost. And I must admit I was frustrated a little bit. I wanted to do my job the best, but sometimes you need to prioritize. So then I just connected with the developers and wrote the release notes. Yeah. I think, well... Sorry. I think the thing that TNT was saying about course nanospannularity, like, often those commits are incredibly granular. You know, one commit might say, oh, you know, this now works with 64 megabyte files or something. And that might actually mean to the customer you can use it on 10 different kinds of architectures you couldn't use it on before. But for the developer, they just, you know, it's a different thing they're talking about. Done. Sometimes it's not good. I wasn't trying to add to this, so please continue. No, that was it. I'm done. I'm done. So I'm a developer, so I know what I put into common loss. And most of the stuff I put in there is really interesting from the documentation perspective because it's really small stuff. And if I'm fixing, but it brings my code more in line with what's document. Right now we don't have the tooling to lag it from it. Like, this is something that affects the user experience or something like that. I mean, we could probably arrange something where we put some code stuff into the common loss that I'm posting to you guys or something, but I don't think we can rely on this to be, to work everywhere. That would have to be done as an arrangement between opportunities of all that we don't have. The tooling doesn't provide what it is. If I may add something, I think that the really good approach to this is to know your developers, right? You need to know the guy, this is the guy you go to if I have a problem or you need to, basically, I feel that maybe sometimes the product documentation of the technical team could be somehow not that integrated with the development team, with the QE guys and all the others. And I think that the good thing to do is to integrate all those people together because overall we are working for the same thing, right? We want to be this product usable and people should know where to go for an app and where to go for a app, right? So that's the thing. Do you have separate documentation and development views and everything? When I had before, like three years ago, we had dedicated technical writer to the team, like Scram came and said that there was a developer that used QE and technical writers. So this was really good. Yeah, this would be... Well, it's not that we are just a separate team. Usually every one of us is working on one thing and you get to know the people. So before that I was working, I worked on the city notes and I know how the guy is responsible for the city notes and you know, I talk to them most of the time and I see that he is in this group. And so it's not that we don't do that. It's more that... it's not maybe that connected as it was like that because also it's sometimes... it's hard to do that if you are working on a bigger project. For example, I maintain the need for a man guide for it which is a beast. It's a huge book with several topics and I couldn't have the expertise to know everything from networking, to security, to system administration, to authentication idea. So, yeah. But for example, now I said that's good because it's a small product. So that scheme works very good. Works really good. I have something else, some great question. It's about do some standards when you are writing the presentation because in my experience the people are most when they have to write something and they don't know how to start. Well actually, Clayton has a really nice acronym and it is this. I will be a little bit rude. It's the reader the fucking manual. So he has a writer and everything the beginning is always the worst part. Because for example, I just want to learn as much as I can about the thing. So I could start. And as for a question with the standards we do use standards. We have a guide wise, we've got a style guide, we've got acrobots which is really cool too if you don't know actually you can just search it in that. So yeah. I want to expand on that question and also the answer. I think ideally then we would have standards and we would also help developers to approach those standards. I don't think we can expect everybody to maintain those standards. That's why we're the professionals and other people do things that they're good at. But we can say for example, if we expect things in outline format we can say how to structure the information so that the initial handoff is more efficient and just less having to dig out the information from one side to the other. We've got an agreed specification for how to communicate. It's like... By the docks no comment, we didn't mean to say that all developers just need to write it all. It's not like that. To have the actual information we can start with. We do test stuff so then maybe think about something else what can be added to the documentation we are also working with GSS guys so we are asking them what is the biggest thing for this project that the customers are calling for so we are there is somebody here on the ground from the docks team it's sometimes about asking the right questions to the developers because sometimes when I'm thinking about developer patch developer tells me I don't know what's inside of the patch because it's upstream it's inside of the network and the code what it does I want to know where the customer could be affected and what problem it fixes do you want to take the context for the customer why is this case important for the customer and I need to ask the developer do you need things in code I need to make him from the other side well, could I be affected by that because some customers may not be affected because they don't use the control in that environment so we must help I mean developers with or by asking the right questions I was like similar experience I'm a developer engineer so I have more problems because I have more problems with specifications I don't know sometimes there are really good ways so you don't know the specifics then it's not good to leave the room to assume things I think that we can wrap this discussion it's not ended but I want to say that the communication is different sticking out time the communication because if 5pm arrives and the queen has this unsatisfactory experience you know heads and body be wrapped next slide okay we only have two minutes so the things that we can think about and