 Hi everyone, my name is Irka and I'm a part of the technical writing team at Red Hat in Brno. My talk today is about teamwork, collaboration, that holy grail of software development and especially so in open source. Primarily though, I will be focusing on where documentation and technical writers fit in all of that. To be more specific, I will start with outlining some of the challenges to teamwork that you may run into at one point or another when working on software. Then I will go over two teamwork methodologies that aim to overcome these challenges. First, the well-established waterfall method and then a more agile variant that we call DevDocTest. By the way, because DevDocTest is a bit of a mouthful, I will be abbreviating as DDT. So keep in mind, I'm not talking about the infamous chemical pollutant. So I will describe the theoretical basics of DDT, but I will also touch upon some practical downsides that could prevent you from using it successfully in your team. Finally, I will introduce some best practices that work for us in getting the most out of DDT. And because it wouldn't be a proper talk without a quote, let's start off with this one. The funny thing is, if you Google for quotes about teamwork, you will find very many that talk about how it makes the dream work and how it divides the task and multiplies the success and how it's generally great. And all of that is true. But you will find very few quotes that talk about how hard it can be to actually pull off teamwork properly. You see, teamwork is usually not something that just happens, right? It's something that you have to put thought and effort into. And unsurprisingly, that gets harder the more people that are on your team or your project. Let's take a look at how that works in software development. If you're flying solo, work on some pet project of yours, then you do the code, you do the testing, and you do the documentation. If there is any at all, which it should, by the way. Naturally, coordination is not an issue here, unless your golem or something like that. When you're working in a small esteem, perhaps with two or three other people, you are all probably a bit of everything. Though some might generally be slightly better at one thing or another. Among the few of you, it should not be a huge problem to work out how to get things done. But now, when your project, your software thing grows in size, it naturally requires more developers and probably also specialized testers to make sure all that fancy code does what it's supposed to. At this point, there is also probably an end user of some sort in mind that is not other developers. So the documentation should follow suit and provide information that is useful, but also comprehensible for those end users. And that is where tech writers come in. This is also where documentation or, well, generally communication coordination might start being a bit troublesome, as it won't always be clear to everyone what needs doing and when. Finally, when you reach the highest level of project complexity, which is usually what happens at the corporate level, for instance, it mayhem, almost. Developers have their specialized teams and subteams with leads, product managers, program managers and so on. Your end users probably require a lot of attention, so customer support and sales specialists come into the picture. Testing is, of course, a lot bigger deal and there is probably a specialized quality engineering team to do it with its own structure, of course. Finally, pretty much the same goes also for documentation. The problem is, to get things done on this level, all these people have to be on the same page about what's to attend to, how and when, which can get pretty messy. To tackle this complexity, there are multiple approaches to collaboration in cross-functional teams like that. Perhaps the most tried and tested is, and arguably the most widespread also, is the waterfall method. I'm sure this doesn't need a lot of instruction. It's a no-nonsense, intuitive process based on sequential progression. I do my thing, then you do your thing, then he does his thing and so on. But the problem with this is that it tends to drag on for a long time, especially in larger teams. Oftentimes, this also means that towards the end of the release cycle, there is a lot of work left, especially for testers and documentation. That results in crunch time, meaning long hours of being overloaded and stressed, or it can result in delays. Honestly, it's a bit of both, usually. So this has also been described as the hockey stick problem based on the visual representation of the workload, as you can see here. All right, to illustrate, let's take a look at a sample waterfall cycle. First, based on data from customer support and sales, the PM and the dev lead plan to address a specific user problem. They task the developer with working on the code. And when that is done, QE ensures that the code works properly. Afterwards, it's time for the writer to step in and create some user-facing documentation. To do that, however, they usually need the assistance of a subject matter expert, an SME, and that's usually the developer. However, at this point, the dev has likely moved on to something else and probably does not even remember much about the thing that is being documented. Still, let's say that they powered through somehow, and now the document should be reviewed by a tester, a quality engineer, to ensure that the described instructions are consistent with what the software actually does. But the tester is probably busy with preparation of the impending release and might even have time for some very rudimentary sanity testing, if anything at all. Finally, when they're done with the tests and the documentation has therefore received the green light from all the necessary stakeholders, it might very well be far too late or the people involved have clocked in dozens of overtime hours. So things get done, but it's not ideal. The traditional counterpoint to Agile, sorry, the counterpoint to waterfall is Agile. Nevertheless, every implementation of Agile is slightly different and my team was now exception. Because it was not really viable for us to jump fully onto the bandwagon that is Agile, we came up with a bit of a hybrid that we call DevDocTest or again DDT. So the essence of a DDT workflow is that documentation and test plans are put together synchronously with the code rather than after it. This aims to make creating and reviewing documentation easier for both the writer and also the subject matter experts involved and also to make testing more efficient for your quality engineers. Ultimately, the intended effect is quite simply better results and more predictability with less crunch and no hockey stick. So let's see how a DDT cycle would differ from what we saw in waterfall. The first big difference is that testers and writers are present in the planning phase. This helps them scope the user stories much earlier and be better prepared for them. Afterwards comes the most important part, which is also called the DDT phase, DevDocTest phase. During this phase, the testers and writers work in lockstep with the developers and they prepare a test test plan and write the documentation respectively while the code is being created. All these they can actively cooperate in shaping the software as it is being developed. For example, testers can point out problematic code interactions while writers can suggest improvements for usability based on their own experience. When this phase is done, testers can then follow the created documentation to test the software, which means they review both the docs and the code at the same time and have an easier time doing it too. As a result, the overall process is faster, more efficient and also give testers and writers more say in the final form of the software. And at the end, there is much rejoicing. So that much at least is a theoretical high level version of DDT. But let's see how that translates into reality. As a tech writer in the DDT workflow, you're essentially like creating a painting of the night sky while the sun is still in its zenith shining bright. You have a reasonably good idea what the night sky looks like and perhaps you even have some astronomical data about the colors, shapes and positions of the heavenly bodies. Still, your imagination has to do most of the work, so you will admit a struggle. Apologies, I need a drink. So you will still struggle. It is not easy. But if you do get it more or less right, you will have ample time to perfect your painting when the stars eventually do appear high above. Also, you won't have to worry about finishing your work before the daybreak. But much like painting the stars at noon, DDT may in some cases not work really well or not work properly and not just for documentation. Sometimes your astronomical data may turn out completely wrong. You see all new code measures in development. So the feature that originally got planned and that you had in mind when you started writing could end up being something utterly different or it may get deep prioritized and pushed off. Also, from time to time, it can happen that a giant meteor just comes hurtling from space and instead of the night sky, you have Armageddon. So, which is to say that that's the feature that gets crept completely. So you need to keep your astronomical data as current as possible. The essence of DDT is collaborating in lockstep synchronously, which is significantly more demanding in many ways than if you go sequentially. You know, it's no longer, now it's my turn to work on the code, then it's your turn to test and then it's his turn to do the documentation. Instead, it's basically everyone's turn almost all the time. And finally, perhaps you're still making a painting of the sun and you cannot possibly start another painting just yet. So what I mean by this is that transitioning from waterfall to DDT can be pretty tough, especially if you're a writer or a tester. This is because you probably have a lot of back loaded work, like left from the old system. But at the same time, you suddenly have to take on the very much front loaded work that is connected to DDT. So this can cause long, long spikes of work where the hockey stick problem just keeps going and going and going. And so the effect is that contrary to what DDT is aimed at, what its goal is, it actually creates a lot more work and a lot more headaches, at least temporarily. So as a consequence of all these pitfalls, quite a few teams I talked to were a bit reluctant, let's say, to abandon what's been working reasonably well for them and move to DDT. One specific reaction that stuck with me was, get the fudge out with this bulldozer, except they didn't say fudge and bulldozer. Anyway, when you're a writer or a tester and some of the teams you work with on a product are agile-ish, using DDT and some are not or are somewhere in between, it basically means you are always in a crunch, either because you need to be taking care of the front loaded agile work or because you're on the hockey stick. And that kind of sucks if you pardon my language. So to make it suck less, and perhaps even make most of the ideals of DDT a reality, we figured out, let's say, a few core tenets to stick to as a cross-functional team. Firstly, writers, as early into the planning phase as possible, work with your product managers or anyone else who is in charge of the user experience and figure out the, well, the intended user experience. What is the issue that the user is facing? What would they like to achieve with the software? What will the changes in the code look like in the front end and so on? This will make your writing a lot easier, but it will also nudge the product person to figure out the UX as thoroughly as possible, which is always good. This goes hand in hand with being generally in the loop. If there is a major change in the development direction and the writer learns about it like six weeks later, then you can't reasonably expect the documentation to be on point and on time. So if you're a developer or a PM and you're using some tracking system where you can name-take somebody, like, for instance, JIRA, keep your writers in mind and toss them a line when something important happens. Next point. If you're using a granular Timebox milestones system, like Sprint, you can try using them to keep the individual teams in strict lockstep, but it's easier and honestly more likely to succeed to use them for priority sorting. So it doesn't have to be like the development exit of this feature is targeted at Sprint 10, so the documentation has to be finished at Sprint 10, but perhaps if development of feature A is targeted at Sprint 10 and feature B at Sprint 15, we should document feature A first, right? Finally, as I mentioned, creating documentation stories very early can lead to them being inconsistent with what the code looks like in the end. So taking part in so-called test batches or hackathons with your testers or with your quality engineers later in the cycle can reveal many of those quibbles and also give you an opportunity to test and discuss them in real time with anybody who's attending, who could be like also support people or it could be your PM, anyone. So basically, this is something for everybody to do, not just writers on second thoughts. Now, I'm well aware that none of the tips that I've talked about here are exactly groundbreaking, but as I see it as a tech writer, even the most complex and cumbersome methodologies should be made of small, simple steps. Ultimately, I don't think we have DDT all figured out quite yet, so you can take this as an in progress experiment review of sorts. Perhaps you could take up the same experiment and have much better results even. Maybe DDT would make perfect sense for your team or maybe you even have no choice in the matter. In either case, I hope this has given you some insights into how to successfully synchronize with your developers or synchronize your developers with your tech writers and your testers and ideally also without much of the sweat and tears that this very often can involve. With that said, I'm not sure if our time is already up, so if you'd like to clarify something available for questions here or later in this code. Thank you, Erika. It was a great, great talk. I don't see any questions in the chat, so probably if anyone has a question like you said, you will be available in this court. Yes, there is one question from Vendula. How exactly do you synchronize your knowledge with DEF and QE? Okay, that would be probably for another talk, maybe even longer than this one, but generally it involves meetings and asking questions and being trying to be in the loop and not just relying on them keeping you in the loop because oftentimes they don't. So I guess being proactive, which I know is a bit of a buzzword, but it sums it up fairly well. Yes, there's one more comment about that because Vendula is saying that it means, it seems to her that it's a lot of meetings and well, yes it is, right? It can be, but given that it's either that or sort of being in the dark and having to spend long hours figuring out what's actually going on, it's the lesser of the two evils, I would say.