Who Writes the Docs?
•0 likes•244 views
Report
Share
Download to read offline
In the wider tech writer world, it’s still common to hear tech writers be certain that developers can’t write good help: the prevailing sense is “Only we can do this.” But those same tech writers often feel under threat in their jobs - feeling like their organisation doesn’t see their value, doesn’t understand what they do. Who should write the docs? Should all developers write docs as a matter of course? Is it even worthwhile having specialist writers? In this talk I’ll try to find some answers to these questions, based on my experience working in many teams - both in teams that have valued tech writing and in teams that haven’t. I’ll talk about the ‘documentarian’ mindset and how that contributes to better software, no matter what your job title is. I’ll also explore the benefits that come from specialist writers and generalist developers working together. And I’ll share the ways I’ve found that people with specialist writer skills (whether they’re developers, tech writers, or other roles) can make the biggest difference to user experience, and through that to their organisations.
Recommended
More Related Content
Recently uploaded
Recently uploaded(20)
Featured
Featured(20)
Who Writes the Docs?
- 1. Who Writes the Docs? Beth Aitman | @baitman lead tech writer at improbable.io
- 2. This is a talk about documentation culture @baitman
- 3. This is a talk about documentation culture @baitman
- 4. Who writes the docs depends on... @baitman - What is valued. - What skills you need.
- 5. @baitman Who writes the docs depends on... - What is valued. Questioning the value: - Do we need really need it? - How hard can it be? - What skills you need.
- 6. @baitman Who writes the docs depends on... - What skills you need. Questioning the skills: - Do you need to be a specialist writer? - What is valued. Questioning the value: - Do we need really need it? - How hard can it be?
- 7. To write well for users, you need... @baitman - ability to communicate decently - product knowledge - knowledge about users
- 8. “Developers can’t write” is a myth @baitman
- 9. “Developers can’t write” is a myth @baitman
- 10. “Developers can’t write” is a myth @baitman
- 15. How to get people involved @baitman
- 16. How to get people involved @baitman - ideology of what their job is - using the documentarian mindset
- 17. How to get people involved @baitman - ideology of what their job is - using the documentarian mindset
- 19. The documentarian mindset - empathy for users and for learners - explain in a way users can understand - use any tool (not just docs) blog.thoward37.me/articles/developer-to-documentarian @baitman
- 20. The documentarian mindset - empathy for users and for learners - explain in a way users can understand - use any tool (not just docs) blog.thoward37.me/articles/developer-to-documentarian @baitman
- 21. @baitman
- 22. @baitman
- 23. @baitman
- 24. @baitman
- 28. The role of specialists @baitman
- 29. The role of specialists @baitman
- 30. The role of specialists @baitman
Editor's Notes
- This is a talk about documentation culture - about who can write the docs, and about bringing more people into the fold. The question that I’m starting out with, around who writes the docs, you can break it down into further questions. Who should write the docs? Who actually writes them? Who’s meant to write them but doesn’t? Does anyone actually write them at all? As a starting point, I hope we can all agree that somebody should probably write something! So in this talk I’m going to talk about what I’ve learnt from the places I’ve worked, where in each of them, ‘who wrote the docs’ has been different. Sometimes the answer was technical writers did, but never anybody else - that was the case in the first company I worked at as a tech writer.
- Sometimes the answer was, nobody writes the docs: that same company actually laid off all of its tech writers, partially because they decided docs weren’t that important after all. More positively, at other times the answer has been “maybe everyone can write the docs”. In my current job, I work at a software company based in London called Improbable, where I was the first tech writer and now lead a small team of writers. For us, a lot of our docs are written and maintained by developers, but plenty of other people contribute too: our testers, our product managers, our support team. So what I really want to talk about is who can write docs, and also in an ideal world who should. Because I think it really matters who does - whose responsibility it can be, both to write docs and to care about them, to think about what docs should be written.
- And to think about this, we need to explore two areas: one is to do with what is considered valuable, and the other is what skills you need to write them. Let’s start with value. The question of what documentation should be written, and who should write it, is very closely tied up with the value of that documentation, and how the people who write it are valued. And people who work on docs often don’t feel that their work is valued. You see so many people talking about, and writing blog posts about how to convince your organisation that documentation, or making other resources for users is worthwhile. And being in a position where your value is questioned is horrible. At best it can mean you get marginalised within your organisation. At worst, it can mean you’re literally out of a job.
- This questioning the value of people who work on docs tends to come in two forms: First one, are the things you work on actually needed? Whether that’s docs, embedded help, a manual. Second one, if there’s agreement they are needed: Do we actually need someone with specialist skills to write them? In other words - how hard can it be? And so the question of value leads to the question of skill. Do you need someone with specialist skills, with expertise, in order to write the documentation that’s needed?
- This question, of do we really need writers, or people who have specialised in writing? I feel like there can be this automatic reaction of, “Of course we do! Why are we even talking about this?”, probably because that question gets used to dismiss us and our usefulness. But I think we should take this question seriously. Because writing well isn’t some kind of special magic that only the experts can do. Pretty much everyone in tech writes as part of their job, in some way or another, even if it’s writing emails, or writing comments in code. And some people are poor communicators, but there are plenty who are good at communicating in writing. There’s no job title that has a monopoly on that skill.
- To write decent user-facing content, you need ability to communicate decently a bit of product knowledge a bit of knowledge about your users. Plenty of people can have that! Which means plenty of them have the start of what it takes to write good docs.
- Despite this, there is still this idea that gets thrown around, that developers are useless at writing. I feel like I shouldn’t even need to say this. But we just need to stop saying it. This is something that should come as no surprise to many of you in this room - so many people here are or have been developers who write docs. And I work with many developers who are excellent communicators - but even the people who aren’t excellent do a great job. Good writing is writing that achieves its goals, and their writing is effective.
- One reason this is obviously a myth is that writing and communicating well are skills that you can learn and improve regardless of what your role is. Some people may have a starting advantage, but ultimately, if you spend time and effort working on these skills, you will get better. But. I don’t want this to sound like this means there’s no point in having specialist writers. In some way you can take what I’m saying to mean that anyone can write, and that can sound really threatening. Especially in the context I mentioned earlier, the context of fearing that your organisation doesn’t see your value. But actually seeing it as a learnable skill is a good thing!
- Firstly because if you’re someone who works on documentation, you’ve spent more time using and working on those skills. Someone else can learn but it takes time and effort - they won’t immediately get to your level. We need to have confidence in our skills, in our level of ability. Secondly because, as far as I can tell, everyone who works on docs has far too much on their plate. If other people can contribute too, we can use that for good, get more docs work done.
- Having said that, it’s not easy to do it. Because the idea that everyone can contribute leads to the worry that “if everyone can do it, I’m out of a job”. It takes away a thing that might have previously differentiated you, made you rare or unique. An instinctive reaction to this is to react to it as a threat: try to protect your turf. Make the work involved mysterious, assert that this stuff can only be done by you and belongs to you. So you can keep having value because you’re unique. I once worked with a junior UX designer, on a team where the developers had lots of opinions about UX. This designer really struggled with that. They started to do things like, saying I’ve been trained on an advanced procedure, so I’m going to spend the next few days working through that on my own and will come back with the output.
- I don’t think it was deliberate, but the implication was: I have special knowledge and training here that the rest of you don’t understand. This is my area, and not everyone can contribute in the way I can contribute. All it actually meant was that the team had no idea what the designer was doing, and so couldn’t see how they were special at all. And you see a similar thing sometimes with writers. Aggressively pointing out mistakes, being precise far beyond the point where it makes a difference. It shows you have knowledge about what’s correct that other people don’t - this piece of writing was wrong before and I made it right, and only I can do that. People do this because we think making ourselves special in this way, protecting our turf, defends our value. But that’s not necessarily how it works.
- For example, when I joined my current job, there was a ton of documentation written and I was their first tech writer. The product we sell is a developer product, our users can’t use it without documentation, so someone always had to write some docs. And that work got shared out, so when I arrived, plenty of people had some experience doc writing. That defensive idea I just talked about implies that if lots of people are on your turf, they won’t see your value. So you might have expected a negative reaction to a technical writer joining - why do we need someone to specialise in this? We’re getting it done just fine. And actually, the reaction was the opposite. Because it turns out, writing documentation is hard! I strongly believe that most people can write something decent - but that doesn’t mean they find it easy.
- So our developers had been doing this work, and they’d seen the struggles involved in producing good documentation. I joined, and I didn’t take over all the docs writing - I helped the people who were doing it already. I didn’t necessarily find it easy, but I did have more experience. And there are a set of core skills that you can get a lot faster at if you have practise, including taking something and making it clearer and more concise, or structuring the information a bit better. So when I paired with a developer on something they’d been struggling with, and could find a better way to express something, or a solution they hadn’t thought of, they could see so obviously how a tech writer adds value. They were happy to have someone to help. This is why protectiveness doesn’t make sense. Writing is hard, and so if other people try it too and see how it’s hard, they’ll appreciate skill and expertise more. Because opening up is a much better demonstration of value than shutting people out. But it does take having faith in your skills and not getting threatened by other people joining in.
- I’ve talked about why getting other people involved is a good thing. Now I’m going to talk about how.
- There is something that getting other people involved depends on. What they think of their job as? For each role on a software development team: should that role look exclusively at its own area, or should they try to see the whole? For example - for developers, do they just write the code they’re told to write, or do they make a product, and think about the whole? Getting people involved does depend on the idea that, if you’re on a team building software, it’s your responsibility to try to build something good. There are a few ideas related to this. Some QAs/testers talk about “whole team quality” - ie, quality is something that is the result not of the work of testers, but of everyone on a development team’s work, so the whole team need to think about it.
- And some organisations would say “UX is a team responsibility” - everyone’s work has an impact on usability, and everyone needs to think about it to produce something good together. In these ideologies, a developer’s job is to build a good product, and do what is necessary to make it good, including write tests and think about users. So if you have this ideology - that the whole team should care about quality, that the whole team should care about UX - then it makes sense that the whole team should care about docs, too. Of course, just telling everyone “you should write docs!” isn’t usually that effective. So I want to talk about a way that I’ve found that really helps people get involved. To do that, I need to explain a concept: ‘documentarian mindset’.
- This is based on a blog post that Troy Howard, one of the co-founders, wrote a few years ago, trying to define the term ‘documentarian’, which is a term that we often use for people who come to this conference, and for people who care about docs.
- And what I took away from that post - go and read it, though - is that a lot of it is really a mindset: having empathy for users/learners explaining in a way users can understand use any tool you have/is appropriate - not just docs This really resonates with me because I don’t feel the main way I make a difference to a company is through writing docs. It’s through having this mindset, which means you don’t start from “my job is to write this doc”. You start from understanding the problems users have, understanding what they’re trying to get done, and trying to help with those problems. Sometimes you will want to write documentation to solve a problem, but sometimes you’ll find that there’s a different solution. Making your product clearer, simpler, more usable. Changing how your software works has to be in scope.
- And I also like this mindset because it’s not an exclusive thing: it’s not something that only people in a particular role can do. You can start being a documentarian by caring about these problems and trying to solve them; like writing, you can get better at this over time. But all it really takes to be good at this is: caring about it, being willing to take the time to think about it deeply, and then practising and getting feedback so you improve. To illustrate the difference this mindset makes, here’s another story about a team I was once on. My role on the team was that I was the words person. Any time there was some user-facing text, I owned that. And we had a way of tagging stuff in our codebase for me to look at the words - we used a kind of TODO comment.
- If you’re not familiar with them, TODO comments are comments you add to your codebase as a reminder that something isn’t finished. So for words things, instead of a TODO comment, the developers would add a TOBETH comment.
- And one day I noticed that our repository didn’t have a readme, mentioned it in a team meeting. So one of our developers went away and created one - and the file had one line in it. And that line just said, TOBETH. And I was actually pretty annoyed! Because if I thought that I should write a readme, I would have just done it. It wasn’t a words problem that the team didn’t have a readme, it was a problem for the whole team. What this shows is that the people on that team would see something that involved words and would immediately go - ah, that’s not my problem, that’s Beth’s problem. Beth will write some words and that will fix this. Because I hadn’t tried to spread that mindset, they saw what I did in terms of the deliverable, not the problems I was trying to solve.
- With hindsight I can see how this caused a bunch of pain. For example, if you have an error message, and you add a TOBETH comment on an error message, you’re probably not thinking about whether the error situation is easy or hard to explain. You just push the problem away to someone else. But if you’ve written error messages, you’ll probably know that they’re hard to write. Because sometimes the error itself is really weird and hard to explain. Because sometimes it’s a really general case, and in order to write a helpful message you need to bring in more information. And sometimes the situation shouldn’t happen in the first place, and really the solution is to change the workflow so it doesn’t come up.
- Ultimately, when it comes to writing an error message, often it’s not a words problem. It’s a fundamental question of how should this program work, or how should the user use it. And that involves a bigger-picture approach, thinking about the whole. And if the person building something has that mindset - instead of seeing it as a words problem that someone else thinks about, they see it as a product problem that they need to think about. A lot of the time, just a little thought can head off problems before they even happen.
- So what I do now is involve my colleagues more in the thought process. Coaching them to ask the right questions to understand the situation. If a developer is working on a feature, I’ll say, ok, you’re building this. You know this feature better than anyone else right now - what will a user need to know to use it? How will they find out about this feature? What docs do you think are needed? I’ll still help out with writing it. If it’s a really big and complex thing, I might well do all of the documentation work. But at the same time, I’m teaching them to think in the way that I think, so that they see how documentation forms an integral part of the product they’re building, and build their understanding of when documentation might be needed.
- For example, there was a team I was working with a little while ago, who were building a prototype of some new APIs, to work out if they would be helpful for our users. I talked to them early on, discussing what documentation they thought made sense. They decided they wanted to keep it really minimal - just a simple code example, only on the project’s github rather than our main docs site, and some comments in the code. I said alright, this is just a prototype, it’s fair enough that you don’t want to put lots of effort into docs at this stage. And I came back to them a few months later, and they mentioned they’d been having trouble getting feedback. Nobody seemed to be using the prototype - even people they’d gone and told about it hadn’t really used it. And I was like, well, do you think this might be because nobody can use it? Because you haven’t given them enough information to use it? And they were like, oh. They could see that to get the feedback they wanted wasn’t going to be possible without documentation.
- This makes the mindset a great tool, because it’s not you telling people to write docs - they’re the ones who’ve thought about it and concluded documentation is needed. It’s a much smaller gap from there to getting them to write it, because they’ve come to their own conclusion that it’s necessary, and often they have a lot of the knowledge needed too. So the thing I really recommend: is asking your colleagues questions, getting them to think about what information users need. In other words, I want you to secretly turn your colleagues into documentarians.
- And where does that leave specialists? Actually, in a really good position. If others are thinking about docs more, making it more of their problem, there are a few things this allows us to do. One is teaching other people, growing their skills. To come back to the idea of value. Often, the most valuable people in an organisation are the people who enable everyone else. Enabling other people is great: it allows you to show your value very visibly, but also to have a much wider impact on your organisation.
- Another thing we can do is focus our efforts, using our experience and skills on the areas that need it the most. If you want to look at the micro level, that can mean spending more time on the difficult writing problems. The information that’s really hard to structure, or the feature that’s really hard to explain. Or, you can look at the macro level, and spend more time on the big questions that often get left behind in the rush. How do we get users to the right help at the right time? How does the whole of our documentation hang together? Is our information architecture effective? Not just helping people with any particular task, but on the big picture. We can use our time to work on making our whole product more understandable.
- And this is where I want to finish. Because if we bring other people in, it can give us this great opportunity, to focus on these really big problems. And working on that level is where I believe that documentarians can make the biggest difference.