[Music]
i'd like to begin by acknowledging the
traditional owners of the bungeeland
land on which i'm giving this
presentation today and pay my respects
to their elders past present and
emerging
i would also like to acknowledge that
this land which i benefit from occupying
was stolen and that sovereignty was
never seeded by the bungeeland people
so i'm going to start with a little bit
of a humble brag but i just moved to
australia's gold coast you might
remember the gold coast from when tom
hanks got covered 19 about 4 million
years ago
anyway we've moved to a relatively nice
area with a lot of development going on
and most of these big development sites
have advertising up around the
construction enticing people to come and
buy an apartment or two
and all these new places have a few
things in common
they all have a stupid aspirational name
like esperance or athena this one that i
took a photo of for you is called delta
which i'm certain they're now regretting
but they also all say something about
architecture
architecturally designed one says
this one this delta one says architect
design homes to suit your lifestyle
so i'd like to have a think about what
architecture means in this sense
clearly the developers of these
properties are relying on you thinking
that having an architect design your
home makes it a bit fancier
when
in reality most of these projects are
just apartment buildings i've lived in a
few apartment buildings and they're
mostly just tiny boxes stacked on top of
one another
but if we dig past the marketing words
we know that an architect is the person
who designs the building
they don't choose the location go out
and buy the materials or do any kind of
building plumbing or electrical work
they don't choose which furniture to put
in the home what the kitchen cabinets
look like or pick the carpet
they are purely about design picking the
shape of the house the layout of the
rooms making sure it suits the area it's
in and the people who are going to live
in it and presumably about getting a
spot on ground designs or a tv show like
that
so can you have a home that hasn't had
an architect
well one of my guiltier internet
pleasures is to browse bad real estate
photos and the way i see it is that
these are the result of homes that
haven't had the benefit of an architect
or
maybe they did have the benefit of an
architect but it was so many renovations
ago that the architect might have wore
mission brown flares and a peace sign
necklace
and in most of these atrocities you'll
notice that the fixtures and fittings
are often quite nice
like this perfectly reasonable bathtub
or this quite lovely chandelier
the thing that's gone wrong here is not
the construction or the furniture or
anything like that it's the design
so to bring this around the long way to
documentation you can think of the words
you write as being like these kitchen
drawers
perfectly good wood cabinetry nice
chrome handles
if only they designed them in such a way
that people could actually use them
and that's what this talk is really
about
i know you already know how to write
great words in the best order
i am certain that you can craft a
procedure that makes grown adults weep
with its elegant simplicity and i just
know that you can come up with the
perfect title for every document every
single time
but none of that matters if you don't
have an architect
if you're starting from a completely
blank slate then lucky you can skip this
step
but i'm betting that most of you already
have something written down
whether it's new content or older than
time itself the best way to work out
what you need is to make a critical
assessment of what you already have
even if what you have is the carpeted
toilet of technical documentation
now this step works equally well if
you're new to the content and need to
wrap your head around it or if you're a
bit too familiar with it and you need to
try and see it with fresh eyes
the best way i've found to start with a
long hard look at your content is to
create a content map
how you do this depends largely on how
much content you have
if you have a few hundred pages
and you don't want to go too deep into
your hierarchy then you can probably
just create a table in a document
if you have say a giant wiki that you're
trying to categorize start with a
spreadsheet
you could potentially go the whole hog
and set up a database if you really want
to spend time on this but in most cases
that would probably just be overkill
so this is a content map i did when i
started my current role and if we zoom
in on the first page you can see i've
only looked at the top three levels of
the hierarchy at least partly because
that's where the bulk of the content was
so we have the top level second level
and third level or page title we have a
url to the page
and the general content type of that
page now i'm going to come back to
content types in a minute
for now though you can already see
patterns starting to form just by
zooming out now i appreciate this is
blurry that was done very much on
purpose
you should be able to see that we have
one huge top level bucket that contains
most of the content
and while the second level headings are
more evenly spaced there's still one
that's much bigger than the others
you can also see that the smaller top
level headings don't have a second level
heading most of the content sits higher
in the hierarchy than in our big top
level bucket so that's something we'll
need to come back and look at
now content types are something that
probably most of you have come across
and there are several different ways of
categorizing content but my favorite one
is the dita or dita model
and that's mostly because it's the
simplest understanding to explain
basically there are three different
content types concepts tasks and
reference
if the content answers the question what
is it then it's a concept
concepts are usually prose paragraphs
that explain what something is or how
something works
if the content answers the question how
do i do it then it's a task
these are usually numbered steps in the
form of procedures
and then if it answers the question what
else do i need to know
it's a reference
this is usually a table or a list of
things that you can look up to find out
information such as what a particular
command does or a list of options
now good documentation should have
clearly defined sections of concepts
followed by tasks followed by reference
and so you can probably start to see at
a glance where my biggest issue was
most of the content i had
was mixed
it had concepts interwoven with tasks
and tasks followed by more tasks without
any concepts at all and very little
reference content
this is a giant red flag
beginners need lots of concepts and
experienced users need to be able to
skip the concepts and easily locate
tasks and reference information
when it's all mixed up it just becomes
difficult for everyone
so now that you have a content map drawn
up
and you can already start seeing some of
your initial problems
you need to turn around from your
content and have a look at what's on the
other side your readers
the first thing to do is to really think
hard about who is reading your docs
the simple answer to this is our users
but that's actually a bit of a cop-out
there's a reason that most technical
writers use the term readers rather than
users
for the people who look at our
documentation
it's because users use software and
readers read documentation
and while that venn diagram overlaps
it's not a perfect circle
your readers are not always or sometimes
not even mainly your users
depending on your product you may find
that sales and support staff use your
docs more than end users do which is the
case in many professional contacts
in the open source world you'll probably
find that people read your docs to
determine if they want to be involved in
your community
or if they want to use your product in
their own project or maybe they might
want to fork your project for some
reason
these readers cannot necessarily be
considered users and it's important that
we write documentation that is
appropriate for those readers as well
now
i'm going to tell you a secret
no one curls up at night with a warm
drink and a great technical
manual so if that's the case
why do people read docs
generally speaking it's because they
want to achieve something
to put that in less abstract terms you
need to work out what problem your
reader is trying to solve
there's a common quote from business
school that says something like people
don't buy a drill because they need a
drill they buy a drill because they need
a hole
when it comes to documentation though
you need to go a step further and ask
why do they need the hole
let's say my friend alex is at the local
hardware store looking at drills
what kind of advice would help them
there's a pretty good chance that when
alex woke up this morning they didn't
think you know what
i don't have a drill i should go out to
the hardware store today and buy one
what is more likely is that they woke up
this morning and thought something like
oh i should hang that picture on my
office wall or i should install a bed
over the staircase
so the content that alex needs is
probably not called how to choose a
drill
the content they need is something more
like how to install beds in
unconventional places
this is an important distinction because
if you get it wrong your readers won't
know if the content is right for them or
worse they won't find your content at
all
now
it's really easy to sit around and have
a think about who the readers might be
but it's even better if you can go out
and find out for real
this isn't always going to be an option
for you depending on how much time you
have available for research
so i would definitely recommend that you
do as much of this as you possibly can
but don't beat yourself up if you simply
don't have the bandwidths to do it all
the main thing is to try and get in
contact with your readers in any way you
can
my preferred method is to start with a
series of one-on-one interviews with
people you already know
if you have a community around your
product or company you can usually reach
out to your top contributors and users
pretty easily
if you're in a larger corporate
environment i would start with sales
technical account managers and
consulting staff
you can then use the information you get
from these interviews to create a short
survey to send out to your wider
audience if that's an option that's
available to you
now this research serves a few purposes
the first reason is that you get direct
feedback on your current docs there's a
really good chance you'll find out some
truths about your dogs but it's even
more likely that you'll have some
suspicions confirmed about the pain
points which is great because now you
have data to back up why you're making
changes and a much better story to tell
about the improvements
but the second reason is a little bit
more long term you might not get any
advantage immediately but in the weeks
and months to come when someone notices
a problem in a document they're more
likely to think oh hold on someone was
asking about this recently who was that
so it actually builds engagement in the
long term
it's also really important to understand
what readers actually want rather than
what you think they might want
in my previous role the developers kept
telling us that we needed more quick
start information
but when we spoke to our readers they
all said they wanted more explanations
of how things worked not just step by
step procedures
so both of those are about getting
started with the product sure but in
terms of the content we actually needed
to write they were quite different
by the same token you also need to find
out if readers actually want what they
say they want one piece of feedback i
once got from a reader was to stop
moving things around
and this was really interesting to me
because when i dug deeper into the
problem it turned out that people found
the documentation so difficult to
navigate they were saving hard links to
the content they needed so if we moved
things those links broke
the problem was not so much that we were
moving things around but they couldn't
find the stuff they needed within our
docs in the first place
in the end the solution to that was to
improve the navigability of the site to
implement a really good site search
mechanism and to get more consistency in
our section headings and procedure
titles so it's clearer what was in each
section
in short the answer to stop moving
things around was to move things around
a little bit more
a lot of technical writers like to do a
user task analysis to work out what
content needs to be prioritized
you can spend a huge amount of time
doing these properly but i really don't
recommend that you do you don't need to
go into too much detail this is really
just a way to validate what you probably
already have in your head by now
so to do a really quick and dirty user
task analysis you need to start with an
idea of who your readers are and the
things your readers want to describe
the lists don't need to be exhaustive
but you should be able to group most of
them into some broad categories that
cover the spectrum of readers and tasks
so if you think about the reader types
first
the way you categorize your readers is
entirely up to you but sometimes the
best way is to start by thinking of a
beginner an intermediate reader and an
expert
or depending on the kind of product you
have you might think of an ordinary user
a system administrator and a support
person
your three readers should probably be
interested in different parts of your
product
they will be trying to do different
tasks and they will need different
levels of help from your docs
don't be afraid to let them overlap a
little bit but try and make sure you've
covered most of the options
so in the example i've got coming up for
you i've used system administrators
sales and support but you could easily
include developers hobbyist executives
or any number of others
so let's have a think about what our
readers are trying to achieve
for each of your readers start by
thinking about how they might begin
what's the very first thing they might
want to do
let's assume that they managed to
complete that first thing without any
trouble what's the second thing they
want to do
and when they've completed that what's
the next thing
again you don't need to be exhaustive
here but make sure you cover the big
ticket items things like installing
configuring troubleshooting that kind of
thing
so once you have those things you can
put them in a little table and work out
how likely it is that a particular
reader will use the documentation to do
each task
if you put the reader types across the
top of your table and all of the tasks
down the side you can get a really cute
little matrix that looks something like
this
obviously this is only the first few
lines but i'm hoping it will give you
the idea
you can fill out each square on the
table with the likelihood that each
reader type will use the docs to do each
task
now note the really important thing here
you're not asking if system
administrators are likely to do a
product installation because of course
they are
you're asking if system administrators
are likely to use the documentation
to do a product installation
the answer to that is a little trickier
and it depends on some things like how
easy your product is to install and how
often a system administrator might need
to do that task
so when you have all the boxes filled
out you can do some simple maths
score a three for high likelihood two
for medium and one for low likelihood
that gives each task a score the higher
the number the more critical the
documentation of this task is
so in my example here you can see that
product research scores are six because
it's only really important to one group
but managing clients scores nine because
it's important to everyone
that means we know we need to spend more
time and effort on documenting how to
manage clients and we can improve the
general product info later on
now the highest scoring things in your
table are called the critical paths
the items with the highest critical path
score is the content that is most
important for you to write
all of this doesn't mean that the lower
ranked things aren't important of course
it's just about finding a place to focus
if you find that your focus points are
not adequately covered in your existing
docs then you have an immediate start
point
so by now you know what content you have
and you have a pretty good idea of who
your readers are and what kind of
content they need
so now we can take a look at the
structure of the docs and work out if
the way things are organized now matches
what it is our readers want generally
speaking humans have a tendency to put
things in hierarchies
so you will probably be facing a
documentation suite that looks a little
bit like this
unfortunately hierarchies like this work
well for when we have a bunch of content
and we need to organize it but they
don't actually work very well for when
we need to find something
to demonstrate i want to think want you
to think about when you last moved house
i've obviously just done this recently
so i can tell you that what i did when i
got to the new place was i started
unpacking boxes and boxes of stuff
so you pick up one thing and you put it
somewhere that seems reasonable
and then days later you're still
wandering around trying to find it
i ended up worming out two cats a full
week late in the month after i moved
because i found one cat's medicine in
one place and the other cat's medicine
somewhere completely different after
three days of searching
so putting things in a reasonable place
is a very different skill and uses a
different part of your brain to finding
things
to get this back to documentation you
need to think about the different
methods people use to find your content
are they coming to you directly they
might type
docs.yourcompany.com into their browser
they might search
your company docs
or maybe they're searching how do i
install this thing or even
what is this thing
when they reach your page what page are
they landing on
are they landing on the top level page
of your hierarchy or some page deep in
the content
and then perhaps the most important
question where do they go next
do they search for something else on
your site do they use a navigation menu
to click on something else or do they
get bored and click away to facebook
one of the most important things i
noticed when i was analyzing the
documentation at time scale was that we
had several methods of navigating the
docs but they all relied on readers
already knowing what they were looking
for
this would be fine if we were catering
only to experienced readers
but we knew from research that we also
had a lot of brand new beginner readers
and we also had a lot of content already
written that was tailored directly to
beginners in the form of tutorials and
getting started information so we needed
to make sure they were able to find it
because our product has quite a few
unique terms for features it was doubly
important that we didn't just assume
that readers knew what those terms were
or what they meant we needed to develop
a way of navigating that not only
allowed people to find the content they
knew they needed
but that could lead them to content they
didn't know they needed
basically we wanted to guide readers
from a place of understanding or i need
to know how to do this thing to a place
of discovery or i didn't know it could
also do this other thing
this is an important step because often
readers know what they want to achieve
but don't know the words to describe
that thing or use they might use
different words to what we might use
so from here we get to a step that i
like to categorize as using your
thinking brain
hopefully the analysis you've done so
far has led you to some natural
conclusions that are now just waiting
for you to express them fully
but even if you're more confused than
ever you can start methodically working
through some ideas
how do you need to arrange your content
to make it easier for your readers to
achieve their goals
what technologies do you have available
in terms of automation and organization
in my current role we decided to
significantly flatten our hierarchy and
implement some intelligence in the form
of keywords and related content
whatever your thinking brain has come up
with it's time to write all your
brilliant ideas down even if they're
incredibly unrealistic write them down
anyway we'll work on cutting them down
to size in the next step
so this step is what i call an
implementation plan and it's where
reality settles back in and we decide
what's actually feasible and in what
time frame
this is the point where it's really
important that you have some management
buy-in on your overall plan
so you might want to make sure you've
shopped your initial research around the
company a bit so that this doesn't all
come out of the blue for your manager
the first thing to do is to work out
what resources you have that's people
time and money
these work in the form of a project
management constraint triangle which i'm
hoping you've seen before
if you don't have much time you'll need
more people to do the work and more
money to cover things like outsourced
contractors or ready-made software or
tools
if you don't have a lot of money you can
compensate by having more people to do
the work and expecting it to take longer
if you don't have a lot of people you'll
need more time and money
the next step is to determine what your
minimum viable product is that's your
starting point
it's the smallest piece of work that can
be done to achieve some benefit
in most information architecture
projects this is usually a small
reorganization of existing content or
adding a small feature such as site
search
from there you can work out what your
next level items are more features more
automation better metadata for seo
improved content
right up to complete rewrites tool or
language conversions and completely new
content
now you get to pick the things on the
list that you can do within your
constraints
now
as a side note it's okay to be a bit
disappointed at this stage it's very
normal to have spent a bunch of time
doing the research realizing exactly how
much better it could be
researching the amazing things you could
do to make it better only to have to
come crashing back to reality when you
realize you can't possibly make it all
happen
mind you from personal experience i can
tell you that if you do get approval to
implement everything you suggest
after that initial rush of approval you
have to face the fact that you're about
to embark on a massive project and that
can be incredibly overwhelming too there
are no winners in this game
so now that you have your implementation
plan i hate to say it but you've got to
put the hard yards in and do the work
i have other talks on how to manage big
projects like this so i'm not going to
go into that kind of detail here but if
anyone is interested in how to manage
that kind of thing you can check out
this link on this qr code for a relevant
video i'll just give you a second to
pull your phone out and have a go at
that
okay one final note that i want to make
about this process is that it's
important to measure your success
this starts right from the beginning if
you have done your planning properly
including things like your content
analysis then you have a good starting
point for later on being able to measure
how things have changed
it's also a great idea if you have the
ability to be collecting data wherever
possible especially if you can start
before you implement changes it gives
you a baseline for measuring for example
if you define early on that one of your
measures of success is going to be
improving the dwell time on each page
you need to know what your average dwell
time was before you started so you can
measure the improvement after your
changes
and a final caveat is that you might
need to be prepared to have your ideas
challenged it's entirely possible that
even after all this research and
planning you implement a new design and
it just sucks
design and architecture is more art than
science after all this building won an
architecture award
and sometimes you might just try things
out and it just doesn't hit
in that case the most important thing
you can do is listen to what your
readers are telling you either directly
through feedback or indirectly through
their actions on your site
tweak things roll things back if you
have to adjust as you go and keep
gathering data
unlike buildings documentation
architecture is constantly a work in
progress
and that brings us to the very end i
just wanted to add that i work for an
awesome company that lets me work on
really cool stuff like this so if that's
something that sounds like it might be
interesting to you then you're in luck
because we're hiring grab this qr code
to go and have a look at our careers
page
and on that note thanks for listening be
kind to each other and i will catch you
live in the q a after this
you