Ana Duarte: Testing Documentation: Why So Technical?

This talk focuses on the importance of effective documentation in software development, particularly from the perspective of a technical writer. The speaker discusses their journey from journalist to technical writer and emphasizes the value of making documentation relatable and accessible. They highlight common shortcomings in technical writing, such as failing to explain the 'why' behind features, and stress the need for documentation to be clear and user-friendly. The speaker shares strategies for improving documentation, including understanding the audience, providing context, and using visual aids. They also explore the challenges of keeping documentation up to date, advocating for better communication between technical writers and product teams. Throughout the session, the speaker encourages the use of empathy in writing, crafting relatable content that helps users achieve their goals.

Hi everyone. Thank you so much for being here. Thank you also Andre for hosting. And also thank you for the Tescon organization for making this happen in this uh special venue. I never thought I'd be in a movie screen and here I am even just for a few minutes. So yeah, this is really amazing. Thank you so much. I hope this helps you somehow. Uh, I don't

see myself as an expert or as a specialist in in really anything. I'm just here today to share a bit of my experiences and hopefully provide you with some insights that will add something to to your life, both professional and personal life. Who knows? And uh, yeah, I I hope you enjoy it. So, a quick bio. Um, I'm from Porto, Portugal, and Wow, shout out. Great. Thank

[laughter] you. Uh, and I always knew I was going to be a writer. At least that's what what I wanted since since they they taught me to write in elementary school. The the thing I remember about writing when I thought about it as a career, because I'm a journalist by training, was to be able to explain something to to someone and help them achieve a task. And

I first thought about this when I was going to high school 20 years ago. I I would like to be younger, but yeah, that's the truth. I went to high school first time 20 years ago, and we had to buy this huge graphical machine from Kazio at the time. I had a cousin. She was older than me. And she said, "Oh, you got this machine. You can

do all sorts of things with this. You can, you know, make a program to go on a rocket to the moon and come back." And I was like, "Really? That's amazing. How do you know that? Do they teach that in math school? And she said, "No, I just read the the manual, the instructions." And I was like, "Okay, so someone actually bothers to write documentation instructions and

someone actually read it reads it and it's helpful. So maybe instructions are really u important after all." And yeah, a few years later, uh I became a technical writer and now I write documentation for for software products and hopefully I help people uh achieve their their tasks their tasks in a in a better way. So I've been working in tech uh for 10 years now. Uh I

also like to read. It makes sense because I like to write. Uh so usually these activities go together as you know. Uh and I try to to read a lot. uh an average of 50 60 books every year. Uh I also love animals except bugs because you know I work for X-ray. So we we try to erase bugs. Uh and yeah, that's pretty much it. So just

before we start a show of hands, who here knows what X-ray is and uses X-ray? Yeah, that's the majority of people. Cool. Thank you so much for using our product. I think I hope you enjoy it and I hope you like our documentation otherwise let me know by the end. So we'll go briefly um to talk about X-ray as a company. Then we get started on the

introduction. Uh we'll go through our journeys, my journey as a technical writer also through my challenges. Then I'll provide some possible solutions for those challenges also examples uh on our documentation and then we wrap it up and we'll have some time for Q&A. [snorts] So X-ray X-ray as you know because most of you use it uh is a company that develops uh a tool management um a

tool testing management for several activities. You can do your tests there. You can do reporting. Then we also have the exploratory app as the name suggests is for exploratory testing. We have exporters just for reporting purposes and we have a special segment for bigger companies who need more tailored and customized solutions which is uh X-ray enterprise. So at least by the time I wrote this slide uh

X-ray was the number one test management solution for for Jira because it's a Jira add-on uh and you can get it in the class marketplace. We have the three product lines I mentioned. X-ray, exploratory app and also exporter. And these three products uh summing up are used by over 10 million testers, Q&As's, developers, engineerings, and they are able to manage 100 over 100 million test cases each

month. So these are some of our customers, people who trust X-ray. I believe you are familiar with at least some of these logos. And now getting actually started. So what I want to to tell you is that at least for my understanding testing documentations very often it fails to explain the context. It shows you the how but lacks the explanation. So where is the why? Uh why

does the product or a feature work the way it does? what is the benefit uh the benefits for the user uh and I believe that we can make documentation not so technical but more relatable and for this we can use cases examples real life uh scenarios to make documentation more user friendly more accessible more approachable and like I said uh more relatable so what do I think

that the documentation uh What are the main features of of documentation? For me, it's scalability because you just can't scale without proper documentation. Imagine a simple process just on boarding a new colleague. If you don't have everything documented, you'll have to stop where wherever you're doing to explain the colleague how the company works, what are their roles, who can they talk to, etc., etc. It's not effective

at all. It's very time consuming. So yeah, you can't scale in any industry um without documentation. Even the Egyptians when they were building the py pyramids, they they knew the importance of writing stuff down or making you know little draws. Uh but what is the main thing about documentation? It has to be useful. If you have a page of documentation that is live and it's out to

date out updated or it's not even complete then you might as well not have anything live at all because it will just cause confusion. So every time you have a page online uh and public make sure it is useful otherwise you might not just have anything at all because it will cause confusion to the reader. And of course content because where is documentation without content? The main

goal of documentation for it to be useful it has to have instructions steps describe a feature describe a product visual aids uh because you are explaining something to someone who may not or may not or may not be uh already involved with the product. So make sure that your uh documentation has content that is useful and clear. A rule rule of thumb know your audience. This is

a tricky one. uh because as an X-ray documentation manager, I know that our users, our readers, they are testers, developers, product managers, project managers, engineer managers, sometimes also designers, but I don't really know who they are. You can never know. AI can tell you that yet. Uh I think who is on the other side of the screen. It can be a tester, a developer, sure, but what

do they know about the product? It can be someone that has been already using your product and your documentation for five years and it can be also someone using uh your product for five minutes. You can tell. So this is one of the trickiest parts about So there are really no rules just conventions and ideas. So what I do is I try to write it in a

way my approach is to write it in a way that it can be easily easily understandable by someone who is just using getting started to using the product and also an experienced reader will be able to to understand it. So where are the journeys for me as a writer? Writing document documentation of course is is a product. it starts I have a um a board where anyone

can open a ticket with a documentation request to create a new page or to just update an existing page. So when they open the ticket they provide me the material for me to to work with. They they explain what they need for from me. So I started doing the research. I will read more about the feature. I'll ask the stakeholders involved about the request. what is that

they want me they want me to to explain to the audience to write and then I make an evaluation is this information enough for me or not can I proceed to the next step or do I need my information or you know a different material do I need screenshots do I need access to an instance for me to try the feature and make sure it works the

way that the ticket is describing and then if so or not I start writing I I start develop developing documentation this is the the most important step and then when it when it ends I review it of course uh it usually helps every time if you can do it. Write documentation of course but then ask uh a colleague or anyone to help you because another u extra

pair of eyes will be really helpful because they are not biased as you are. And for this, if you have a small team like I do, you can also rely on AR to help you proofread and to make sure that docu documentation is uh ready to go from a a different perspective because like I said, you are too biased when you write something. So always ask someone

or AI to help you uh get a different opinion. Then it goes live. But as you know um documentation is a reflection of a product. A product is a live beast. Therefore, documentation is also a live beast. So, it has to be always under maint under maintenance. uh you will have to update it eventually because products change, features change and so you'll have to keep an eye

on everything that you you write and be close to the product team and ask them if there were any changes because most likely there were and they failed to tell you because uh yeah it's not uh really on their mind to all the time to let you know about the changes. So yeah, it will the cycle actually never ends. Now regarding more specifically speaking uh about the

journey on an actual page what I try to do is I try I start by writing uh an overview an introduction which consists of a summary of the product or of the feature. This will allow the reader uh on a very short time to be able to understand if he landed on the right page and if this page will help him or not uh achieve their their

goal. And then I keep going with the concept breakdown. So I'll explain what the components are of this feature, what it will achieve, what are the benefits uh for the user and then I provide examples for this. Um usually I try to use screenshots, visual aids just to make sure that you don't only write technical stuff. You always provide con context. How will that feature work on

a specific scenario? So if you can all the time try to provide examples, use cases, real life scenarios and for this use your imagination. You can also use AI tools but what ifs are your friends all the times. So try to write and all always provide examples of how that instruction would work uh on a on a concrete example on a life a real life scenario and

then some actionable insights because it's likely that uh the person will have to read another page or read uh relatable content. uh so provide that information as well and also personally I think it's also a good idea to provide uh on a on a footnote on the top on the the down part of the page um troubleshooting information because sometimes the person will read the page and

it can they can have questions about it. So provide an email or a link where they can contact the support team and uh explain their doubts and um expose their questions to the support team. Now this all of this brings challenges like everything. What for me are the main challenges in writing documentation? Like I said, I think testing documentation and product uh documentation in general is too

technical because it doesn't explain the benefits for the user. Uh it only explains the how, not the wise. So I really think this this part is missing from the majority of of tech documentation. Keeping the documentation up to date is also hard because I unfortunately I believe that documentation is the most neglected part in software engineering and developers and PMs they don't really like to to write

documentation. So most of the times they forget about it. Uh so they develop the product and they are about to make the release and then oh damn we forgot to write the pages. Let's now open a ticket and ask Anna to do it. So I have to do it for yesterday. Um and yeah uh also they when there are uh changes to the feature or to the

product they forget that that has to be reflected on the documentation of course. Uh so the communication factor uh is is a challenge and like I said since it's the most ne neglected part um of software engineering it's hard and it's a constant struggle and a challenge to make other stakeholders care about So how do I try to solve this? I try to ensure that the documentation

is technical yet rel relatable by every time I present a new feature or a product I explain the why beyond the how. You can see in this example for associating test exe executions with a plan. So we say that uh in X-ray centralizes tracking and simplifies reporting by consolidating results in one place. But then again what's the benefit because it improves organization ensure all relevant tests are

account accounted for enhances analysis etc etc. So make the statement of what the feature is and how it works. But then explain what's the benefit for the user. The same here because we as an company tech company now we also have AI features and we have to explain all the time what is the benefit especially being AI what is the benefit for the user using these uh

new features AI features. In this case uh for the AI test case generator it will accelerate and simplify the process of creating test cases from plain requirements. So as you can see I have almost uh all the introduction to paragraphs just explaining the benefit uh of this Also we have a section called ttt tips tricks and tutorials. Uh this is a whole section section of our documentation

designed to just demystify technologies uh comp techn technicalities of of the of our technologies. So how do I write this? We try to avoid complex jargon provide simple and clear explanations by writing tutorials by writing pages that can offer you workarounds. So it's like you are writing documentation not so much for a professional but more for a friend just to try to put ourselves more on the

reader's shoes. Now uh some examples regarding doc documentation dos and don'ts. Okay. So when you are writing documentation, always be sure to provide an explanation, provide context. As we seen before, try to explain the the advantage all the time you are writing a page about the feature. Don't ever assume that the readers will know what you are writing about because like I said, it's very hard to

know your audience and even if you do, you won't know for sure who is the person on the other side. Is he a tester? Is he an engineer? Is he a manager? Is he a junior or a senior? If so, then he can be using your product for five years or for five minutes. How can you tell? You just can't. So, never make assumptions. Never assume that

you are writing for someone who already uses and knows your your feature or your Always be uh straightforward. Provide concrete and clear examples. For instance, avoid saying when a user you are writing about a user input, but what user in input is that? Is it a username? Is it a password? If so, just say it what it is. Don't be abstract. If it's a an incorrect password,

then call it password. Don't call it a user input. Also for the examples use use visual aids and step-by-step guides because otherwise your documentation is already boring for most most of the people. It is what it is but uh you can make it less boring if you enhance it with visual visual aids. For me you can use also videos but it will require different set of skills

that not every company or technical writer has but screenshots for me are the go-to solution for this. So provide screenshots uh of the feature you are writing about. Provide it with steps and try to relate it the most in the most close way we can with the text. I use um little little circles with numbers as you can see here. Not yeah you can see it the

screen is is quite big. Uh so that's how I try to do it. It's the best way I think to to relate your text with a with a visual aid with a screenshot in this case. So now regarding the the role of of a technical writer uh if you are successful you will know it because no one will tell you most likely. Uh so you are an

invisible worker because if the documentation is is actual useful and fulfills its purpose it will go unnoticed. No one will read a documentation page and then think, "Oh, this is so helpful. It really helped me. Let me email the technical writer saying he did a good job." No, they will be happy that their task uh is done and they they were happy to achieve their goal and

they'll just move on. On the other hand, if there is a documentation page that it was actually useful, but if just a comma is out of place or a screenshot is outdated or if a link is broken, all hell will break loose when something goes wrong, they will let you know for sure. So yeah um if you are a technical writer or if you are thinking about

about becoming one be prepared to be to be an unsung hero to make invisible work because that's just the way it happens even it happens with us when you are you know when you are trying to set up Nike furniture you check the instructions they are helpful you were able to to do your your job and that's it you won't be thanking anyone so yeah it's a

silent success role And for this uh there is a quote I really like by Marit Van Djk which is the Schroinger's documentation paradox. I don't don't know if you are into quantum physics and you know about Evan Schwinger uh scat but the thing is if there are no documentation no one will read them. On the other hand uh if documentation is not existent or if even is

even outdated everyone will complain and you'll know about that for sure. So yeah, it's a it's a paradox. It's a dilemma, but usually this is what happens. And you you may you may agree with me. I think also we we can compare uh our role to to the to the industry of where we are now to theater and movies. So when you see a movie or any

kind of show, you don't see the sound engineers, the light engineerings, the makeup artists, people who actually make the show happen. They are invisible workers and if they would do a good job, like I said, you won't even be thinking about them. So it's it's pretty much the same with technical writers and also uh the same with referees. I don't know if you like football. [snorts] Please

raise your hand if you do. Okay, some people. Yeah, great. So, think of a football match. You go to to to a football match to see, you know, some in a way to see a show, to to vibrate with your team, to see goals, all of that. But if by some chance the the referee keeps stopping the game or stalling it, the game isn't flowing, the match

is not exciting because it's constantly being interrupted. Uh so when that happens most likely the referee I mean of course it's a football match there are other factors the teams cannot be uh providing you a good match but um most likely when the game is constantly being interrupted or stopped is because the referee is not doing a good job and everyone will complain about the ref. On

the other hand if the referee is doing a good job you won't even noticing it which is great because the game is flowing and you are there to watch the teams play. Um, so it's pretty much the same. If a referee does a good job, it will be invisible. If not, everyone will complain. So, uh, what my what are my main takeaways for you? I believe [snorts]

that knowledge must be shared, otherwise it's not real. That's why we write documentation. We write documentation because we have products and we want our users to make the most of our products and to enjoy our their features of course and to be able to perform their their daily professional tasks uh in the most effective way they can and for that they need documentation and the documentation must

be useful all the all the time. If it's not useful just discard it. You might as well not have anything there because it will cause confusion. it will cause your readers to complain about it to open tickets to your support team asking why this is not working, why is the documentation wrong about it. So yeah, always make sure that your documentation is useful otherwise just remove it.

Might as well not have anything there than providing um and useful and wrong information. And about being technical because we are right we are talking about documentation for for tech products. It has to be technical, of course, because it is what it is, but it doesn't have to be that technical or too technical. So, make it relatable. Don't just stand there and write uh about how it

works, but why does it work the way we do? What's the benefit for the user? What's the actual advantage of using the the feature that you are writing about? So, put yourself in the reader's shoes, provide examples, provide it with clear um language, avoid jargon, and make sure that you that you always put yourself in the reader shoes. And this is hard because like I said, you

can't really know who the other person is on the screen reading documentation. So make it as relatable and user friendly as you can because you know document documentation and testing uh is all about providing the best we work we can to our to our customers and to make sure they have a good experience using our product and uh it's mostly about telling stories about explaining how something

works the the way we does and how the person will have a benefit from that. Uh so always you can't provide stories without good examples. That's how it works. So always be willing to tell stories, provide examples, provide screenshots, provide context, uh real life case scenarios, what ifs. What ifs are your best friends when writing examples and use cases for documentation. And if everything goes smoothly, you

won't uh get feedback only if things go south. So be able to end a success that goes unnoticed because it's the way we works. We know that not only from the technical writing experience but from our us experience when consuming any kind of instructions if the instructions are useful and well written. No one will tell you about it. So be prepared to to be invisible and to

be an unsung hero because quite often your success as a writer will will go unnoticed. And don't take it personally and in fact take it as a compliment because it means that it actually helped someone achieve their their task and that was our goal from And uh yeah I think this is it. If you >> yes we have a lot of questions. Yes but I will use

my position like can I ask the first question >> please? >> Uh you are good at telling stories in writing. Thank you. >> I'm just Does it mean that you are also good in telling stories like when you speak like including anecdotes for example? Anecdot is also about telling a story. Like I said it's jokes are tricky because they only land depending on the on the audience.

So it's it's tricky to know uh who are you talking to all the time. But usually when you are I mean I'm I think I'm good at writing. I don't think I'm that good at public speaking. Sorry. [laughter] So it Thank you. Thank you. See it worked. My joke worked now. But yeah uh so what what I try to do is I tried to to challenge myself.

That's why I'm here because I don't really believe that if you are a good communicator you are good in writing. that you it doesn't really mean that you are good uh speaking or explaining but I try to do that I try to always keep a component of storytelling in my communication processes >> okay can you show slide the uh yeah we have lots of questions so how

you started using AI to finalize your technical documentation >> yeah I use it uh basically every Okay, so since I am the only technical writer in the company and I have to write and maintain documentation for three products at least products that have new features almost every week uh I have to to get uh an extra help and I mostly use chat GPT um and I use

it for proofreading tasks. So every time I write a page I ask I have a special prompt for that that I built. Uh, I ask help to get it's like an editorial assistant to to proofread and to to review my text before it goes live. Also, because as you may have noticed, I'm not an English native speaker. So, it also can help with that. Um, and it

can also uh help when I'm trying to write uh a page from scratch and I don't really know where or I'm not really sure about the best way to to start doing it to to approach it uh or to have a good structure for the page. It can also help with that. So mainly I use it for those two reasons to help myself prepare for the page

if I'm blocked by some reason and then to review it by by the end. >> So yeah, I use it every day. And which tools do you prefer? >> Uh, for now I've been using Shach mostly. >> Mhm. >> I also use Grammarly. It's it's not AI, it's a Chrome extension, but for editorial uh purposes as well. >> Mhm. Okay. Uh, [snorts] so the next question, thank

you for your presentation. If you could change something in how the documentation is created, what would it be? >> Make it part of the definition of done. >> Okay. That way I I don't have to be constantly uh asking them about do you have the material for me to write the documentation? Did you forget about it? No. If it's part of the of the definition of done,

for sure they will remember it. They will care about it and that that way they can help you >> in a better way. Yeah. >> Okay. Clear. Yeah. So next, what's wrong with snakes? >> Zero logic about the the way they move. You know, they don't have legs. They don't have arms or hands. I mean, what's with that? It's just super confusing for me. That's why I

hate the snakes. >> Okay. And bugs have too many of legs. Yeah, [laughter] they compensate. >> Yeah, I mean, I've never I've never even touched one, but uh yeah, just the way they move is super strange for me. >> Probably snakes the same about you. >> No, because I have legs and arms. So, it makes sense how I can move it. For me, it doesn't sense. doesn't

they just nah too strange too strange for me. >> Okay. Uh seems ah no are there any common mistakes you notice people make when writing documentation? >> Yeah they don't they don't put theirelves in the reader's shoes. I mean they make assumptions. Um they don't think about the audience. They don't ask a lot of questions. This is very important. I I didn't mention that when you are

writing documentation. Don't be afraid to ask questions. because some of the most of the times the the PMS um will not provide you with with enough information for you to be able to write a good page. So yeah, sometimes people are writing without enough knowledge to provide a good set of instructions for the reader. So for me that's one one common mistake and not making it as

relatable as they can not putting themselves in the reader's shoes. >> Those are the most common mistakes I see. The next question is actually related. Seems that being technical writer requires a high empathy like to everyone besides snakes. [laughter] Uh perhaps that's why developers cannot write documentation. >> Not sure I I can speak for them but for my experience when I when I speak to developers about

documentation they just don't like writing it. they just prefer to write code and it makes sense right that's why hopefully unfortunately that's why I have a job because they don't like to write documentation for them it's it's a boring task uh but yeah it requires high embathy but even higher patience um so yeah I I think they don't like to write documentation because in a nutshell they

just want to write code and get it over with documentation it's it's like an extra task uh for them and it's boring to them. So that's why I think they don't like it. >> Okay. I know that developers actually say that the best documentation is the >> because this is a source of truth. This is the only place which is true >> and documentation can lie can

be out of date, right? >> Yeah, that makes sense. I have never thought about that like like that but yeah it makes sense. >> Okay. isn't the easiest for developers to write technical documentations like I guess not for you not for like product owners but for developers because they have all the best knowledge about the >> they do but they are too biased and they are overly

technical uh they don't have they they are not sensitive enough to care about the reader's perspective they don't really they don't care at all uh about providing examples use cases real life scenarios videos um most of the times they are not able to express themselves uh in the best way writing so yeah I'd say it's not the best task for them and like I said they don't

like to do it anyway so [laughter] >> uh okay just from my side I am a developer and I highly recommend recommend using testdriven development and pair programming in this case developers uh communicate with each other. They think through all the cases. They describe all the cases in tests and so it's quite normal for them to describe the information in text as well. Highly recommended. So have

you uh experimented with writing documentation in Girkin you know given when then and having automated tests linked to that girking scenarios behav development basically BDD given when then? >> Yeah. No, I haven't. Uh I I wrote documentation about uh girking and automated manual tests, but uh I've never um done that. So it's a it's a recommendation. Thank you. So yeah, but I I've never done it. >>

Okay. Do you think there is a chance AI can replace your job in the future? >> This is one of the main discussions today. Even not my job only, but everyone's job. But um Yes and no. Because for instance at the time uh in our case we use conflence as a back office to write our documentation and as far as I know there is no AI tool

in the moment that can try our product our features go to conflence get the screenshots get the bullets with the the circle with the numbers inside um on the screenshot and match the text with that. As far as I know, no AI tool can do that So I think that it will always be required for a tech company to have someone doing that that manual task. Uh

replacing I don't know. I don't have a crystal. Maybe it it will happen, maybe it won't. The best thing I I I know and that the best thing that we can do for now is to embrace it and to be able to use AI for our own benefit because it's like Darwin said, you either adapt or you you die. So the best thing for me that's what

I do now. I don't fear it. I use it for my own benefit. I embrace it. As about the future, who knows? >> So you you are not afraid of AI yet. >> It has been an advantage for me. I don't have I'm the only I'm the only technical writer in the company. They AI can help me uh proofread and be an editorial assistant. So I'm actually

grateful for it for now. But who knows what's going to happen. Maybe ask me a few years later. Maybe I I'll be angry that they they took my job, but for now they they don't. >> Okay, Claire. The next Do you have questions for uh time for questions? Mhm. Okay, nice. We have a lot of questions. Uh are you familiar with concept of software developers in test?

>> I was sorry I was just reading there and I got confused with it. >> This is actually the ones. Do you have advice for software developers and tests who need to write the commendation? >> Yeah. Uh try to break down the the communication barrier. If you know there is a technical writer in your team, try to be close to them so that they can be able

to perform a better job by getting to know in advance what is it that you are developing. Uh and try to read a lot. That's that's my main advice because usually they don't also like to read. Uh I do that myself when I'm when I buy a product or any of furniture. It bothers me to know okay I have to read the instructions before I do this.

I know it's boring but the best way to make you a good writer is firsthand make you a good reader. So my advice would be would be that work on your reading skills, consume documentation, uh make yourself knowledgeable and be close to the technical writer because you need them as much as they need you. >> So invest in that relationship. [clears throat] >> Uh okay. So the

next question is how do you know when to stop? Uhhuh. When to stop? Uh so like documentation is full and is not over full like because yes in my practice I also have seen documentation which was a huge work doc word document like of 300s pages that nobody can really read to the end. >> Yeah. So the rule of thumb um in in documentation and and in

journalism because I'm a journalist by training. So my approach to documentation is like I explained a top- down approach. I start with the most important stuff so that the reader can know right away if the page will be useful for them or not and I go to the less important details or or elements. I try to always have in mind to describe an idea or a concept

per page and if you by the time you get a big scroll I can't really quantify it for you but uh always try to limit yourself to an idea or to a concept per page if it's more than that then you will require a different page and create a whole section for that feature if that's the matter because the attention span is short And people don't like

to spend too much time on a page. So try to do that. Try to break your page into sections and have an interactive table table of contents that can help the reader with the page navigation. So yeah, try to limit one idea per per or concepts per >> Okay, looks like an instruction how to generate really lots of pages. But uh how to understand it's not only

about number of pages but how to understand that you are not going too deep in details probably unneeded details. >> Like I said if you see the scroll is too long um just try to break it uh into into another page. It's highly subjective. It depends on what you are writing about but try to keep it one concept one idea per page and not with a long

scroll. >> Mhm. Okay. Okay. uh how to maintain requirement documentation for example if the system is used internally and neither users nor developers want to note things down so I don't really write internal documentation I I write public and customerf facing documentation but like I said the best thing you can do to be able to keep documentation up to date wherever it is about uh requirements uh

or or any kind of of structure or feature. Keep a good relationship with the developer team. They are the the best people to be able to explain to you what are the changes, how do they work. So keep an eye on them, be close to them. Uh because like I said, they will most likely forget to tell you about the changes. So my best advice is keep

a close relationship with developers and and PMs. >> Okay. So you need to often go to go smoking with developers. >> Why not? For instance, yeah. [laughter] Okay. Uh is a good practice to include the update of the documentation together the with the code changes by developers. >> Uh that's a separate thing. uh you have to keep in mind that you are writing uh in in my

case we write for our audience because these are the people that use X-ray because since it's a tool for developers and Q&As and testers but you can be writing about any kind of tech product that is not meant to be used by by developers or or by testers or coders or whatever. So always keep in mind uh the profile of the the the persona that that you

are writing to uh because if it involves a lot of code it can be too technical and it will be repulsive to them. So always have in mind the the persona uh when you're writing >> Mhm. Okay. So when the only documentation is a developer and some user stories like injur uh how and where should I start as a QA? >> No idea. I've never wrote documentation

based on user stories. So maybe if you can come up to me uh before this session, we can try to find an answer for this because I've never um wrote documentation for from user stories. So I usually write documentation based on tickets uh PM's open or on PRDS uh and information that I gather for myself. So I I've never stories. So maybe I don't know who wrote

this anonymous >> but I would say that actually user story is basically ticket >> just just in Jira you can create ticket >> the tickets they open to me are specific for documentation purposes. So yeah I have a specific for board just for that >> so they already know how to express themselves when they are opening a >> but feel free to to come to me and

we can discuss about it. >> Mhm. Okay, just a short comment. Your job is quite similar to QA which also often goes unnoticed and when some no until something is broken. >> Yeah. Yeah. Yeah. We are together in the struggle. [laughter] >> It is. Yeah. It's the same pains. >> Uh great job advocating for technical documentation. You mentioned it. I am not an expert, but you are

a strong advocate for neglected aspect of software development. >> Yeah, happy to do it. I like to root for the underdog. So, thank you for for the compliment. >> Maybe we could use AI for testing the documentation. Not testing documentation, but testing the documentation itself. >> Yeah. Yeah. Yeah. I I also do it sometimes after I ask the AI tool to to review it and proofread it.

I also ask him are you able to understand if you are an Xray user how this works and what's the benefit for you? Is it this understandable if you are a customer? Uh yeah I also do it that that's that's a good point. Yeah. >> And the last one >> not really question but thank you so much. Thanks.