Thank you, everyone. Hi, so, I'm a technical writer. I work on documentation. I've worked
on mostly for external users, developer tools, and now at Google working on docs for internal
people working on development teams. It's something I care about a lot because I've
seen how much of a difference it can make. Great documentations can
help your team ramp
up, help users adopt your product, decrease your support burden, and we heard a few of
the other speakers talk about the difference documentation can make as well. I hope that
what I can do now is expand on that a bit and how to create documentation that is effective
and really useful. There is tons I would love to say but I've only got ten minutes so I
will try to tell you my top five things that I've learned to try to make documentation
better. So, firstly, I want to talk about why we write docs because understanding the
reason behind something makes it easier to do well. Documentation exists to help a reader
to achieve a goal. It's about usability, really. So that means that you don't want to start
with how do I document my piece of technology? That's the kind of the wrong question to ask.
Instead, you want to start by working out what does your reader need to get out of it?
So you work this out, and then you stick firmly to writing stuff down, only the stuff down
that helps them with that. Reader needs can be as narrow as I need to set up this CLI,
or I have this small other engineering task, or they can be as broad as I'm new to the
company and I need to understand this whole architecture so I can contribute to the team.
Your docs will become way more useful when they focus on the bits that will help the
readers get that job done, including the things that are relevant, and not including stuff
just because it's connected, or you kind of know about this thing that's related. So,
for example, if you're writing end-user documentation, for something that is a feature you fill,
you might know a lot about how that feature was designed, what the trade-offs were, it
doesn't mean it's relevant in that context. The question to ask yourself is: does the
reader need to know about that? That's how you decide whether or not it matters in that
context. That leads us on neatly to the second point which may be counterintuitive, but writing
lots is not a good thing. Documents is at its worst when you have a huge sprawling doc
set, maybe that's a wiki, where there's a lot of information that's poorly structured
so it is difficult to find what you need, and half of it is out of date anyway. So don't
write more documentation than you can carry. This is so important for writing docs that
are not just useful today, but in six months' time, a year's time as well. Remember that
you don't need to cover everything. Instead, thinking about writing documentation that
is what you can commit to, because if you can't commit to maintaining something, it
will get out of date. And I'm sure all of you have suffered from out-of-date docs that
can be useless, or sometimes either actively harmful, sending you down the wrong path.
If you try to be comprehensive, you can end up desperately trying to cover every small
thing, and not actually adding any value at all. This is an example I love of what happens
if you try and cover every single detail? It is much better to ... [Laughter]. It is
much better to focus on a few core things and cover them well, so you have a handful
of things that are well crafted than a bunch of stuff that doesn't add very much value.
And bad documentation trains people to expect nothing from the docs. So it's well worth
weeding out stuff that you know isn't useful or is wrong. If the one thing you take away
from this talk is that you go home and get rid of useless or outdated documentation,
I will be delighted. Number three is something that can help with you starting writing, but
also makes docs better for users. Or for readers. I've worked with a lot of engineers who have
wanted to write some piece of documentation but struggle when they sit down to a blank
page and don't know where to begin. I don't do this, like what I do is the strategy I
use is to start with an outline, thinking about those questions that we talked about
in point one, who is this for? What is the reader trying to get done? Asking those questions
about what your readers need and then using those as the heading for your docs. You fill
in your answers and notes as bullet points and you're most of the way to having something
written the written that is useful. At that point, all you need to do is fill in the details
and make sure you're only answering those questions, only covering those points, it
helps with you point number two, helps you to write less. So this helps for the writing
process. But it also makes the doc work better for users, because if you structure that documentation
around the information that you've worked out that they need, and you haven't made the
stuff that doesn't help replace them, then you've got a long way, because those headings
will make your doc a much more readable. My next writing tip is another way to avoid getting
blocked which is as simple as talking it through out loud. So the same as rubber-duck debugging
where you can work out problems by speaking about them. I can't count how many I've sat
down with an engineer where they've said I can't explain something. I've said tell me
about it, and written down exactly what they said and that's what they use in the docs
because it was perfect! My theory is that we speak a lot more than we write, and so
we find it easier to express ourselves when speaking than when sitting down to write something.
So this is useful to kind of get you unblocked. It also helps make better quality docs because
usually a friendly kind of conversational style is much easier for readers to take in.
We have a tendency to be a bit formal and stuffy when writing things down, like it's
a piece of homework for academic paper. You can avoid that. If you read what you've written
out loud, you can get the sense of does this seem natural or not? Is this how you would
say it? So, the last thing I want to say on writing is that there is a huge difference
you can make that documentation's usability by applying some readability techniques, and
I'm talking about docs but a lot of this applies across the board to many types of writing.
Part of readability is just making things look less like a wall of text. What you're
trying to do is give the reader a way to understand the information at a balance, so by using
headings, if you're clearly market the sections of the docs - marking the sections of the
docs and what they mean, that helps someone get the information out. Bonus points if those
are connected to the job the user is trying to get done. If you're writing things to do
with code, using code formatting is probably something your reader wants to jump to anyway
so you're helping them get to that information quickly. When you say if you find yourself
writing, so you if do, this, and this, turning that into the structure it should be, which
is a list, it makes it much easier for someone to understand the meaning of that at a glance.
You should also try and keep your paragraphs nice and short. This is kind of a bit of a
guideline but trying to keep one idea per paragraph avoids the wall of text, and if
you can keep sentences to roughly below 25 words, again a guideline, but that's what
people tend to find easier to parse. There are also some writing-style techniques to
help your readers get the information much more quickly. The first one is what I call
call front-loading a sentence. This first example, you need to do X if Y is the case,
this condition putting it first means someone can skip the other thing. You can also just
instruct people directly. This can feel rude if you're not used to it but it is kinder
and useful for the reader to say this is the thing you need to do rather than it's possible,
or using the passive voice "this can be used". Lastly, trying to connect up your headings
to whether a your user is trying to get done. We are talking about custom code generation.
The task for your user might be this is about writing a custom code generator. Trying to
connect these. I've written up a lot more examples on my blog as well and I've got a
link at the end with some more details. I said five points. I lied. There's a six th
meta point! Documentation can be really useful, but we don't write it for its own sake. As
I hope has been clear, it's there to help people get stuff done. And often through writing
documentation, you discover much bigger problems. Maybe there's the procedure you're writing
about is really complicated and messy. Maybe you're building something that has a concept
that is really hard to explain, or maybe you find out that things don't work in the way
that you should they should. If you find as you're writing you realise you're documenting
around the problem, that's a really good point to think about whether you can make the underlying
thing better. Because instead of - if, instead of writing a doc, you can fix the thing, you
should fix the thing. So, thank you!