WEBVTT 00:00.000 --> 00:10.000 Hi, I'm Daniel, I'm a technical writer and I've made some mistakes. 00:10.000 --> 00:18.000 Prepare for this talk, I was looking back on the larger open-source documentation project. 00:18.000 --> 00:24.000 I have been a part of, so not one of tasks, but kind of big multi-step projects. 00:24.000 --> 00:28.000 And I really wanted to tell you about a success when this is not that talk. 00:28.000 --> 00:34.000 Instead of coming back to a tiny failure, genuinely tiny failure, 00:34.000 --> 00:43.000 I am kind of haunted by my very first attempt to lead documentation work for open-source software project. 00:43.000 --> 00:52.000 I was a technical writing student at university, and I needed a capstone project with real clients. 00:52.000 --> 00:58.000 And a lot of my classmates were doing unpaid labor for their employers. 00:58.000 --> 01:03.000 And I thought, you know, if I'm going to work for free, I'd like to be for the comments. 01:03.000 --> 01:08.000 And I was a computer science student before getting into tech writing, and so I was like, alright, I've never been here. 01:08.000 --> 01:10.000 Open-source. 01:10.000 --> 01:14.000 And I reached out to the containers of Python library that I used and was fond of. 01:14.000 --> 01:19.000 And to protect the guilty and the innocent, I'm not going to actually read you my print email. 01:19.000 --> 01:23.000 But the conversation with something like this, I am a tech writing student. 01:23.000 --> 01:25.000 I want to work on your documentation. 01:25.000 --> 01:32.000 I could have be ready to use a guide or fill in some undocumented API references, or have a bunch of undirected ideas. 01:32.000 --> 01:36.000 And the sound of the project was actually quite enthusiastic about this. 01:36.000 --> 01:39.000 He said, oh my gosh, a real tech writer to work on a docs. 01:39.000 --> 01:42.000 I've got some ideas too. He's written on my suggestions. 01:42.000 --> 01:46.000 And then he says, what do you think, maintain or be? 01:46.000 --> 01:50.000 Well, the other maintainer for the project says, you know, this really sounds nice. 01:50.000 --> 01:55.000 But as the primary maintainer right now, I, I don't think I have time for this. 01:55.000 --> 01:59.000 I wouldn't be able to mentor you and how to use Git or how to fill the docs or do anything like that. 01:59.000 --> 02:05.000 And it's not worth to change anything about the docs until the big two dot zero rewrite is finished. 02:05.000 --> 02:08.000 This is not how I wanted this conversation to go. 02:08.000 --> 02:12.000 But in this conversation, in retrospect, I did that every single thing wrong. 02:12.000 --> 02:15.000 We're actually, we both did. We had vague outcomes. 02:15.000 --> 02:18.000 We had bad assumptions about what a tech writer could and should do. 02:18.000 --> 02:22.000 We had bad assumptions about what a maintainer could and should do. 02:22.000 --> 02:29.000 We had no explicit connection between contributor skills to the actual needs of the software. 02:29.000 --> 02:34.000 And we even couple docs work unnecessarily to other activity. 02:34.000 --> 02:36.000 This is not a catastrophe. 02:36.000 --> 02:44.000 In some ways, I was very lucky. This could have been an ambitious project that blew up my semester. 02:44.000 --> 02:49.000 Instead, I, like everybody else, I did some pre-work from my employer. 02:49.000 --> 02:52.000 Now, that version two does your rewrite. 02:52.000 --> 02:55.000 Shift used after I graduated. 02:55.000 --> 02:58.000 We just didn't do anything in this respect. 02:58.000 --> 03:09.000 So we had the classic failure mode of software documentation, which is to do nothing. 03:09.000 --> 03:13.000 So in the last few months, I've been thinking a lot about this very early episode of my career. 03:13.000 --> 03:23.000 And I've been asking what it would look like if writers and developers knew how to work together from some very early conversations. 03:23.000 --> 03:30.000 And the rest of my talk is about three common high consequence problems for open source free software projects. 03:30.000 --> 03:38.000 When it comes to maintainer and tech writer collaboration, some ways to think about those problems. 03:38.000 --> 03:41.000 Some problems with the way of thinking about those problems. 03:41.000 --> 03:48.000 And a preview of a free resource to help you do this work in a very practical actionable kind of way. 03:48.000 --> 03:54.000 The problems that we get into here, they're not actually, they're not almost common problems. 03:54.000 --> 03:58.000 The other ones that I think you're probably already familiar with, like scope creep. 03:58.000 --> 04:05.000 I'm not going to get into, but I think these are most interesting and most damaging because they're widespread. 04:05.000 --> 04:06.000 They're kind of invisible. 04:06.000 --> 04:09.000 They undermine trust between collaborators. 04:09.000 --> 04:17.000 And they have negative consequences for the consumers of your documentation. 04:17.000 --> 04:24.000 So when I talk about maintainers through this, I want you to understand that I'm not throwing stones here. 04:24.000 --> 04:28.000 I also an open source software maintainer. 04:28.000 --> 04:31.000 I have been on both sides of these conversations. 04:31.000 --> 04:33.000 I've made some sticks. 04:33.000 --> 04:36.000 And I'm not cater. 04:36.000 --> 04:39.000 So problem one is inwardly focused. 04:39.000 --> 04:43.000 It's when a maintainer fails to recognize their own capacity. 04:43.000 --> 04:46.000 What time do they have available to do work? 04:46.000 --> 04:47.000 They're skills. 04:47.000 --> 04:48.000 What are they good at? 04:48.000 --> 04:49.000 What are they bad at? 04:49.000 --> 04:50.000 They're assets. 04:50.000 --> 04:53.000 What existing docks and tools are already at hand? 04:53.000 --> 04:54.000 And avenues of support. 04:54.000 --> 05:00.000 Who can they turn to to get advice or additional help and that kind of thing? 05:00.000 --> 05:02.000 This can cut in two directions. 05:02.000 --> 05:04.000 You can have over an underestimating. 05:04.000 --> 05:10.000 So for instance, a very confident thing can experience, you know, 05:10.000 --> 05:18.000 Halifax and can see about their own skills and the superficial similarities between programming 05:18.000 --> 05:20.000 and writing work. 05:20.000 --> 05:24.000 And that can lure the maintainer into believing that with very little experience they're going to be a quick 05:24.000 --> 05:27.000 and confident technical editor. 05:27.000 --> 05:32.000 And a self-conscious maintainer can have them encounter with a writer and think, 05:32.000 --> 05:35.000 I've never done this kind of work. 05:35.000 --> 05:37.000 I don't know how to do it. 05:37.000 --> 05:39.000 Like, let's not. 05:39.000 --> 05:45.000 Or to defer to writers in ways that are maybe unhelpful for the software itself. 05:45.000 --> 05:52.000 And the idea that comes up in this way is when a maintainer thinks that I don't have time for 05:52.000 --> 05:53.000 documentation. 05:53.000 --> 06:00.000 And that means the software project as a whole doesn't have time for documentation. 06:00.000 --> 06:03.000 So whatever direction this cuts, it is natural. 06:03.000 --> 06:07.000 maintainers typically have more extensive development work than what we might turn, 06:07.000 --> 06:11.000 docs or product work. 06:11.000 --> 06:14.000 And that makes me two problems too, which is outward looking. 06:14.000 --> 06:18.000 So this is quite similar to problem one, but it's when a maintainer fails to 06:18.000 --> 06:24.000 inquire about or recognize in tech writers and other collaborators kind of coming from 06:24.000 --> 06:30.000 maybe different disciplines their capacity for their time to do work. 06:30.000 --> 06:31.000 They're skills. 06:31.000 --> 06:34.000 What things that a tech writer knows and doesn't know. 06:34.000 --> 06:35.000 The assets. 06:35.000 --> 06:43.000 What does this person bring to the software project from their kind of world of expertise? 06:43.000 --> 06:44.000 And avenues support. 06:44.000 --> 06:48.000 Who else are they bringing to this party? 06:48.000 --> 06:50.000 This also cuts into directions. 06:50.000 --> 06:53.000 That's own underestimating phenomena. 06:53.000 --> 06:59.000 For instance, one might assume that a tech writer doesn't know how to use Git. 06:59.000 --> 07:05.000 One, you can have the course of knowledge where you're so familiar with your problem 07:05.000 --> 07:09.000 domain that you have someone coming new into some work. 07:09.000 --> 07:12.000 And you assume that, oh, well, only the basics. 07:12.000 --> 07:22.000 And the basics is so far beyond, you know, kind of the average first off the sheet knows. 07:22.000 --> 07:27.000 Another example of this is when. 07:27.000 --> 07:38.000 Like, I've seen a tech writer like I bring with me a lot of tools and assets that are not in your source repository, right? 07:38.000 --> 07:39.000 I have templates. 07:39.000 --> 07:43.000 I have weird tricks to produce documentation. 07:43.000 --> 07:50.000 And that's something that's maybe invisible unless you ask about it or I share about it. 07:50.000 --> 07:55.000 Again, whichever direction this cuts has like over underestimating. 07:55.000 --> 07:59.000 This is also not unfamiliar. 07:59.000 --> 08:05.000 It's a natural outcome when writers are pretty infrequent contributors to free software. 08:05.000 --> 08:09.000 And it's really hard to recognize what you've just never seen before. 08:09.000 --> 08:14.000 And then there's the third problem which is when we maintainers, tech writers, 08:14.000 --> 08:22.000 other collaborators together fail to link our collective strengths capacity interests to the projects needs. 08:22.000 --> 08:27.000 So in an old school tech writing situation, you do this thing information plan. 08:27.000 --> 08:33.000 This is very heavy weight planning apparatus for sorting this stuff out. 08:33.000 --> 08:39.000 And the open source software world is tends to be kind of looser. 08:39.000 --> 08:41.000 We don't do this kind of thing very often. 08:41.000 --> 08:47.000 Or if we do do it kind of done poorly because we're just not accustomed to doing this work together. 08:47.000 --> 08:50.000 And documentation is kind of an unloved area. 08:50.000 --> 08:54.000 It's easy to look at your documentation and see nothing but gaps. 08:54.000 --> 09:02.000 And then the conclusion you draw from that is, well, any documentation work must necessarily be filling some on that need. 09:02.000 --> 09:07.000 Whether that's true or not. 09:07.000 --> 09:16.000 This failure to link capabilities together and the products interest together is it is also a natural problem. 09:16.000 --> 09:22.000 I'm kind of repeating myself here a little bit, but tech writers and link hangers don't do a lot of work together. 09:22.000 --> 09:29.000 And so we don't do this. And if we do do this, it is through inventing a brand new process from scratch. 09:29.000 --> 09:33.000 And why should we expect that to go well? 09:33.000 --> 09:43.000 So in today, I'm kind of this question that is carrying you through this work is what if you could see yourself and your collaborators and your project plan clearly. 09:43.000 --> 09:46.000 Again, earlier in the process. 09:46.000 --> 09:50.000 And so we can start by taking stock of ourselves as maintainers. 09:50.000 --> 09:56.000 We can have some questions like how much time do you have as an maintainer for docs work. 09:56.000 --> 10:00.000 Is this in addition to existing responsibilities or is it not? 10:00.000 --> 10:04.000 What are you going to sacrifice to do this work? 10:04.000 --> 10:07.000 What skill plan regularly to this project? 10:07.000 --> 10:12.000 Are you already in a habit of viewing code? Are you already in a habit of viewing docs? 10:12.000 --> 10:20.000 Are you writing code? Are you writing docs? Are you doing project management work? Are you doing community management? 10:20.000 --> 10:29.000 What tools do you use regularly? Do you already have an already familiar with Mark Down or Restructure Text or whatever you got? 10:29.000 --> 10:36.000 Do you have a static site generator or a content management system? Do you have hosting for these things? 10:36.000 --> 10:41.000 Are you already equipped with spell checkmenters for matters? 10:41.000 --> 10:52.000 What documentation already exists? There's an area where a lot of underestimation happens where lots of people have rough drafts, notes, outlines, things that are actually published. 10:52.000 --> 10:57.000 And I think those things actually do count towards the resources you already have. 10:57.000 --> 11:02.000 And when was the last time you changed the documentation? What, what, what, what, what didn't go well? 11:02.000 --> 11:10.000 And what do you tell you to work on? What's going to have that motivation to bring that work to completion? 11:10.000 --> 11:16.000 Then we can kind of direct these kinds of questions outwardly. Two are would be collaborators. 11:16.000 --> 11:21.000 So let's ask some questions of our tech writer here. Right? How much time does the tech writer have? 11:21.000 --> 11:26.000 Is this a brief consultation? Is this someone who's going to take up residence in your documentation? 11:26.000 --> 11:33.000 What skills do they use regularly? Are they more of an editor? Are they more of a writer? Do they like to play with the tools? 11:33.000 --> 11:37.000 Or do they like to play with the words? 11:38.000 --> 11:42.000 What tools do they use regularly? Are they already using Git? 11:42.000 --> 11:46.000 A little salty thought. 11:46.000 --> 11:50.000 When was the last time the tech writer changed the documentation? 11:50.000 --> 11:55.000 I think there's a world difference between someone who has submitted a typophics to your project, 11:55.000 --> 11:58.000 then has not looked at your project before. 11:58.000 --> 12:04.000 And that gap is like, doesn't seem that big, but it is enormous. 12:05.000 --> 12:12.000 What are your tech writers? What are you excited to work on? Again, what kind of motivation are you bringing to see this work to completion? 12:12.000 --> 12:18.000 And then we can talk about making a plan that is focused on where all this stuff meets. 12:18.000 --> 12:23.000 And so when we take all that stock we've done. 12:23.000 --> 12:28.000 And we are going to find the intersections of maintainer time, skills, tools, experience, interest, 12:28.000 --> 12:33.000 and user needs. 12:33.000 --> 12:36.000 And then we start looking for gaps in the plan. 12:36.000 --> 12:42.000 Where don't you in the writer quite neat? Where don't you and the projects needs? 12:42.000 --> 12:44.000 Not quite neat. 12:44.000 --> 12:51.000 And where you find those gaps, then you can start to see ways to mitigate that. 12:51.000 --> 12:57.000 So you can look to who else in your community can help you bridge those gaps. 12:57.000 --> 13:07.000 Now these questions are fine. If you are thinking about them, you are already well ahead of most people thinking about documentation. 13:07.000 --> 13:12.000 But now that I've said through this, you might have noticed a little bit of a problem here. 13:12.000 --> 13:14.000 This is a super abstract. 13:14.000 --> 13:20.000 I want you to make lists of things about documentation in the abstract. 13:20.000 --> 13:21.000 I don't know. 13:21.000 --> 13:25.000 Besides, it's super uncommon to have a writer just show up for no reason. 13:25.000 --> 13:33.000 My story as a university student, that's a never event for an open source project. 13:33.000 --> 13:39.000 Instead, what you probably have are specific things you want to achieve with documentation. 13:39.000 --> 13:43.000 And now you need a collaborator to help you achieve those things. 13:43.000 --> 13:46.000 And you have to recruit someone into the process. 13:46.000 --> 13:52.000 So now we have to think about these questions in terms of a hypothetical collaborator. 13:52.000 --> 13:57.000 This is a really, really hard problem, and I don't think you should do it. 13:57.000 --> 14:01.000 So instead, it's like invert this intellectual exercise. 14:01.000 --> 14:04.000 What happens if we start with a documentation problem to solve? 14:04.000 --> 14:06.000 What does solving that problem look like? 14:06.000 --> 14:10.000 And then what is solving that problem look like? 14:10.000 --> 14:14.000 And then what does the actual project that brings that solution into the world look like? 14:14.000 --> 14:16.000 That's like a plan. 14:16.000 --> 14:19.000 So what resources would you need? What collaborators would you need? 14:19.000 --> 14:21.000 What are the deliverables for that work? 14:21.000 --> 14:24.000 How do you know when you're ready to start? How do you know when you're really finished? 14:24.000 --> 14:28.000 What if we could order off the menu, seriously? 14:28.000 --> 14:41.000 So, the way to this talk is to, is that I am excited to preview a work in progress that gets us closer to that ideal. 14:41.000 --> 14:49.000 Let's call it documentation project archetypes, and it's a field guide to open source documentation work. 14:50.000 --> 14:55.000 This work is, this is like documentation for anything documentation. 14:55.000 --> 14:58.000 It's being funded by Google Season 2. 14:58.000 --> 15:02.000 So, big thank you, Aaron. I think you're here. 15:02.000 --> 15:04.000 Thank you Aaron. 15:04.000 --> 15:10.000 And so through research interviews with open source maintainers, with tech writers, 15:10.000 --> 15:15.000 who have contributed to open source and through hard one personal experience, 15:15.000 --> 15:21.000 I found 18 types of documentation efforts in open source free software. 15:21.000 --> 15:26.000 And right, I'm letting brief guides to cover the dozen or so most important. 15:26.000 --> 15:31.000 I've broken them down into a few somatic areas, given each one a dramatic name, 15:31.000 --> 15:36.000 and I'll give you a few examples and take you through one of them specifically. 15:36.000 --> 15:39.000 So the first, the somatic area is planning and evaluation. 15:39.000 --> 15:44.000 This includes projects such as the audit, where you inventory and evaluate what assets you are, 15:44.000 --> 15:49.000 what assets you already have, the discovery, where you do a vertical slice of documentation work 15:49.000 --> 15:54.000 to validate or de-risk larger effort. 15:54.000 --> 16:04.000 And the study, where you do user research to find out what the users of your software need from the documentation. 16:04.000 --> 16:11.000 There's this production theme, which is actually producing new documentation. 16:12.000 --> 16:17.000 Projects in this category would be the manual, where you're writing linear prose documentation, 16:17.000 --> 16:21.000 or the sample where you're producing sample code and demos. 16:21.000 --> 16:23.000 There's revision and transformation. 16:23.000 --> 16:31.000 Projects like the curb cut, where you're doing accessibility remediation, adding all text things like that. 16:31.000 --> 16:38.000 Or the translation, which is internationalization and localization work. 16:38.000 --> 16:41.000 There's the tools and process area. 16:41.000 --> 16:47.000 So the factory, which is automating docs production, things like generating API references. 16:47.000 --> 16:53.000 And the migration, where you move from one tool to another that presents documentation to your audience. 16:53.000 --> 16:57.000 And so that's the one I'm going to look at closely here. 16:57.000 --> 17:01.000 So each archetype comes with a short breakdown of what makes that project distinct. 17:01.000 --> 17:04.000 So what is the migration? 17:04.000 --> 17:10.000 We're going to start with a name and synopsis, briefly describe this thing in a sentence or two. 17:10.000 --> 17:17.000 And to give you the key words to recognize later on when you are doing migration work, 17:17.000 --> 17:26.000 that when you hear upgrade or replot forming or porting or retooling, that this is potentially the migration in action. 17:26.000 --> 17:27.000 Next is the audience. 17:27.000 --> 17:31.000 Who are you meant to serve by doing this work? 17:31.000 --> 17:39.000 To the migration, it's a little complicated, but it might be delivering pages faster on page load. 17:39.000 --> 17:42.000 It might be improving the editor experience. 17:42.000 --> 17:47.000 So you can produce more docs faster. 17:47.000 --> 17:48.000 When and why? 17:48.000 --> 17:52.000 So what problems does this kind of documentation project address? 17:52.000 --> 17:57.000 What problems does this documentation project not address? 17:57.000 --> 18:05.000 Tasks and deliverables, or how you will know when you have finished the work. 18:05.000 --> 18:07.000 Key people, who is going to do this work? 18:07.000 --> 18:10.000 This is almost never just one person. 18:10.000 --> 18:15.000 You know, even if you have a writer producing lots of words, someone has to read those words. 18:15.000 --> 18:18.000 You need doctor viewers. 18:18.000 --> 18:23.000 If it's a very well-researched project, you might have lots of support roles involved, 18:23.000 --> 18:28.000 to do hiring and payments. 18:28.000 --> 18:36.000 So you'll need HR and finance and legal and that sort of thing. 18:36.000 --> 18:40.000 The last major section here is going to be risks to consider in your plans. 18:40.000 --> 18:45.000 These are the hazards most strongly associated with this kind of project. 18:46.000 --> 18:55.000 So for the migration, it might be trying to fit in rewrites or redesigns while you're also doing the migration way. 18:55.000 --> 19:03.000 And so this is to give you the opportunity to make mitigation of those risks part of your project plan early on. 19:03.000 --> 19:12.000 Now, I know this is not the whole story, and this means that each archetype ends with links to more resources about that project type. 19:12.000 --> 19:15.000 Now, maybe this is still pretty general. 19:15.000 --> 19:19.000 I'm still kind of asking you to draw the out. 19:19.000 --> 19:20.000 And some of that's intentional. 19:20.000 --> 19:22.000 I know you already have your own project management practices. 19:22.000 --> 19:27.000 You're in community norms around how to do work within your software project. 19:27.000 --> 19:32.000 But I'm really trying to help you to, like, prime you to start these conversations 19:32.000 --> 19:37.000 and to be opportunistic about the resources available to your project. 19:37.000 --> 19:45.000 By being aware of the different kinds of docs work, you can take advantage of your own time when you're motivated to do documentation work. 19:45.000 --> 19:51.000 Or encouraging existing contributors to scale up their participation from one-off tasks to large projects. 19:51.000 --> 20:03.000 And to advocate more strongly and make better use of major resources that you can get for your project, such as grant funding or co-workers getting involved. 20:03.000 --> 20:15.000 Open source programs and other avenues that direct really big meaningful resources to your open source software and your documentation. 20:15.000 --> 20:21.000 So, if you will have one of all this work, you can go to dbt.com slashvastem.255. 20:21.000 --> 20:32.000 There's a rough draft of the migration archetype and some information there about how to keep up with this work and to give some feedback. 20:32.000 --> 20:40.000 And with that hope, I hope that I have finally put the rest of the ghost of that very early project in my career. 20:40.000 --> 20:44.000 And I hope that we can do more to make some docs together. 20:44.000 --> 21:02.000 Yes, the question is in my familiar with pattern languages. 21:02.000 --> 21:04.000 Yes. 21:05.000 --> 21:10.000 I'm blanking on the name of the author, but there's a famous architecture. 21:10.000 --> 21:15.000 Yes, Christopher Alexander, famous architecture book. 21:15.000 --> 21:17.000 It's really fascinating. 21:17.000 --> 21:22.000 I highly recommend it, even if you have no interest in architecture. 21:22.000 --> 21:33.000 It's a fun thing to you can turn to a random entry and see a description of like a potential solution to a potential architecture problems. 21:33.000 --> 21:37.000 Yeah, I have not made the explicit connection here, but now that you mentioned it. 21:37.000 --> 21:39.000 Yeah, that's definitely an influence. 21:39.000 --> 21:56.000 Because also in the intersourcing community, they have explicitly taken all pattern languages as a way to spread patterns in the community for how to teach or how to find patterns that work to get stuff done to change your community to do better work. 21:56.000 --> 21:58.000 So, this is very, very similar. 21:58.000 --> 22:08.000 I think you have a look at the intersourcing community, because I actually have a library of patterns on it for doing intersourcing. 22:08.000 --> 22:09.000 There's probably some books back there. 22:09.000 --> 22:14.000 There's the intersource comments and also the open practice library. 22:14.000 --> 22:18.000 It has a, yeah, and I know there's some other resources along these lines as well. 22:18.000 --> 22:27.000 I've, I'm blanking on names now, but like there's, there's a lot of stuff from like the UK government, like GDS, 22:27.000 --> 22:35.000 and there's some stuff from 18F, US governments that kind of like has a kind of playing card format. 22:35.000 --> 22:40.000 And so yeah, I'll update this page with some links to some of that stuff as well. 22:40.000 --> 22:43.000 But yeah, it's a good, good shot there. 22:43.000 --> 22:45.000 And the second quite well full of questions. 22:45.000 --> 22:51.000 This is not only irrelevant for the source projects, it's not just open source. 22:51.000 --> 22:56.000 I mean, that's like, it's nice to have creative constraints. 22:56.000 --> 23:11.000 And yeah, I think there's a few, and I've taken some notes on, and I'd like to embellish on later, perhaps, of projects that are kind of more corporate in nature and, and I kind of thing. 23:11.000 --> 23:20.000 And I think, yeah, I think there's, there's some stuff at the periphery of this as like a explicitly open source kind of resource. 23:20.000 --> 23:34.000 And, and there's actually grew out of some work where I was trying to describe like tech writer archetypes, like the kinds of people, like what the, the kind of modes of working that as tech writer, I've seen. 23:34.000 --> 23:41.000 And so I think, I think there's lots of opportunities to grow on top of this work. 23:41.000 --> 23:44.000 Thank you so much.