Supporting non writers to write effective content
•1 like•121 views
Report
Share
Download to read offline
How can you make a large amount of content work for users when you don’t have the resources to write and maintain it yourself? One solution is to support writers to create user-focused content themselves.
Recommended
More Related Content
Recently uploaded
Recently uploaded(20)
Featured
Featured(20)
Supporting non writers to write effective content
- 1. Supporting non-writers to write effective content Beth Aitman (@baitman) Technical writer at Improbable 29 January 2018
- 2. Game world We make this bit} }
- 3. Documentation is content to help developers get stuff done
- 4. Documentation is content to help developers get stuff done
- 5. We needed our developers to write content
- 6. We needed our developers to write content
- 7. The product isn’t complete until users know how to use it
- 10. Keep it minimal
- 11. We don’t have a style guide.
- 12. We don’t have a style guide.
- 14. Reviewing
- 15. Reviewing
- 22. Training
- 23. - Questions to ask before you write documentation eg: Who uses this feature? What is the user task? - Ways to structure writing to make it readable eg: Lots of headings, short paragraphs and sentences, bullet points, using bold - Some writing tips eg: Use the active voice, instruct rather than describe, remove tautologies, front-load sentences Training sessions cover:
- 24. Challenges
- 25. But it’s worth it!
- 26. That’s it. Thanks for listening!
Editor's Notes
- Hi! So I’m going to be talking today about working with non-writers - specifically, with software developers - to write content that was useful for our users. I’m going to talk about what worked, and what challenges we faced; but first, I’m going to explain why that needed to happen in the first place.
- Eighteen months ago I joined a software company called Improbable as their first ever technical writer. What Improbable does is, we make a platform that lets other developers build really huge online worlds. If this is a huge multiplayer game, we sit underneath that make it go. So our users are developers: they write their own code that interacts with the code that we provide. And because of that, because it’s a developer product, our users need documentation.
- When I say documentation, I don’t mean paperwork. It’s closer to something like a manual. And normally when someone says the word manual you think of the useless pieces of paper that come with your washing machine - you know, the ones you put straight into the back of a drawer and never look at again.
- But the reason you do that is, for that kind of device - you don’t need a manual. You can figure out how to use it through looking at it and exploring it, more or less. That’s not true with the kind of product that Improbable makes. It’s our users’ code talking to our code. There aren’t any buttons to press - it’s more like, there are magic words you need to say. And if you don’t know what the right magic words are, or what will happen when you say them, you can’t do anything. This is why developers need documentation. That’s why Improbable knew they needed a technical writer, and that’s why I was hired. But when I joined there were around fifty developers working on our product, split across five or six teams, and one of me to work on our content.
- And all of those teams were busily working away on our product, changing things and building new things and working on and on. When they built something new - we needed to tell our users how to use it, so we needed to write new documentation. When they changed something - that meant documentation needed changing. Maintenance is really important: out of date documentation is misleading, unhelpful, and degrades trust. And there are lot of features and aspects of our product. So that’s a lot of content we needed. There was no way I could do it by myself.
- And also, a lot of the time, I wasn’t the best person to write it anyway. Our developers are experts on the product, and lots of them help with customer support, so they do understand our users. It would take me a long time to understand the full details of a feature and then write about it. It’s much more efficient for them to write it, and I can help with making sure it’s clear, and user-centred, and useful. I had to learn not to be protective or defensive about my area. Instead of saying “documentation has be done by me, only I can write well enough to do it”, I’ve learnt to share my skills so that I can share the workload. I couldn’t have managed if I’d tried to do it all, and our users would have suffered.
- There’s a fairly persuasive case that we need to write this content, and it’s this simple. If a feature is isn’t documented, none of our users will know how to use it! Unless our users can get the information they need, we don’t have a product. And actually, people tend to take pride in their work: there’s a strong idea of craftsmanship among software developers. They want to produce a good product, something that our users like and use. So when I came to talk to our developers about the work they were doing, it was pretty straightforward to discuss what documentation was needed, and to ask them if they could write at least a first draft.
- Working out what to write was one of the challenges. And the thing that really helped here was being guided by our developers’ expertise. As I said, they’re very knowledgeable. So instead of going to them and telling them what to write, I’d ask them what they thought users needed. Deciding what to write is answering the question “What information do our users need to get the job done?” It takes me out of the equation: they’ve decided what’s important.
- The thing I could really help with was more on the writing and information structure side. Apart from anything else - I did a humanities degree, and they’re pretty much all computer scientists. I spent three years writing essays, whereas they don’t tend to be experienced at structuring information in that way. So once we’ve decided on a topic to cover, I can help them work out how to structure that information, and the best ways to present it.
- I want to come back to that question, “What information do our users need to get the job done?” It really helped to be minimal: if our users don’t need that information, leave it out. It’s ruthlessly functional: everything has to be targeted towards helping users achieve goals. This has two benefits. One is that I’m asking for as little as possible from our developers, so minimizing how much goodwill I’m spending. It also means it’s really easy to justify what I have asked for. But being minimal, and focusing on what’s functional, has other aspects too.
- For one thing, we don’t have a style guide. For the content that we write, I don’t care about style. I don’t care about consistency of voice. All that matters is that our documentation is clear, that it gets the job done. If two pages sound like they’re written by two different people, that doesn’t stop our users understanding the information we’re telling them.
- It involves letting go of a bit of professional perfectionism, and publishing things that I know I could do better, if I had the time to do it all myself. But good enough, for us, is good enough: our documentation doesn’t have to be pretty, it doesn’t have to be perfect, it just has to work. A style guide is just a tool, and right now for us, it’s not a tool that helps us achieve what we want to do.
- I want to talk a bit about the practicalities of writing and reviewing. There’s one fundamental thing that makes it possible for developers to contribute to documentation: our content lives in the same place that our developers go to write code every day. Who’s familiar with GitHub? It’s just a way of storing code - and you’ll see here, our documentation is in a folder here. It’s just in text files - not a complicated file format, with a special application you need to open it - keeps it really simple. But it means that every one of our developers has access to this, in a place they go every day. This is a really key thing: if you want other people to write content, it has to be in their normal workflows, otherwise there’ll be a lot of friction.
- And when they make changes to the code, they make something called a pull request, which looks like this: basically, please pull my changes into the main thing. So when they make documentation changes, it happens in exactly the same way. Pull requests for code get reviewed by other developers - they comment on the changes and suggest improvements. So we use the same workflow for documentation. Developers are used to it, so it makes it incredibly simple: there’s nothing new to learn.
- And I spend a lot of my time reviewing content written by developers. And I don’t just want to correct them and make it right - I want to make sure they can do better next time. They grow and improve, which makes life easier for me because I have to make fewer comments, and it makes life easier for them because they need to make fewer changes. I want to show you what that looks like. In particular, I very rarely rewrite something for them.
- I try to explain what’s wrong, or what’s confusing, and see if they can make it better.
- Here’s an example where I show what the problem is, but let the developer solve it. I know the answer, but I want them to come to the conclusion, so that they know how to think in the right way next time.
- It’s pretty unusual for me to just say “change it to this”. And if I do, I try to explain why. I don’t want it to be “Beth is waving her mysterious writery wand and making it better”; I want them to work out what’s better, understand why it’s better, so I can pass my skills on.
- This is one area I differ from the usual developer review: I try to say when I think something is great! Especially when something has a lot of comments about improving on it, it’s nice to call out what’s been done well as well.
- And sometimes - this is one developer commenting on another developer’s work, making a suggestion that makes it clearer.
- This is basically the dream.
- One thing I’ve started doing, to help a bit more with this, is running training sessions. This is actually something requested by our developers: so instead of them learning this bit by bit through my review comments, they can get it all in one go instead.
- The training I run covers some straightforward tips to get their writing closer to “good enough”.
- There have been a few challenges along the way. One, that some developers are better writers than others. In particular I’ve had a few non-native speakers who’ve found it harder to write clearly. But if they’re willing to put in the time to try, I’m willing to put in the time to help them, and I’ve seen big improvements. Second challenge: when should I do it myself?
- But it’s so worth it. Had a conversation recently - there’s so much documentation work to do, if I could have enough writers to do all the work, would I? And I realised I wouldn’t. Our developers understand what a writer does, because they do it too. And they appreciate our skills, because they can see that we know how to make stuff better! I think we’d lose that if they saw documentation as just the job of writers: having not enough of us means that we get a culture where our developers do consider documentation to be their responsibility, and they do see that content is a necessary part of making our product complete.