How to Fix Your Documentation Problems the Agile Way

1. COMPANIES STRUGGLE WITH DOCUMENTATION
Companies struggle
with documentation.
In most enterprise
companies, its
something middle
and senior
management say the
need but from a
prioritization
perspective, it
gets no time or
expertise.
Documentation ends
up being something
that is hastily
slapped together at
the last minute so
we can claim we "we
documented it."
Yet, few companies’
look at the
documentation they
put together and
can say they are
proud of it. The
same companies who
struggle with
documentation are
also looking at
Agile as a way to
make their project
delivery better.
Most of the
information about
documentation in an
agile context is
sparse and
unhelpful. As a
result, confused
companies wrestle
with what to do to
solve their
documentation
problem and
continue down their
path to agility.
DOCUMENTATION
DOCUMENTATION
DOCUMENTATION
What we assume to be documentation problems are in fact
"communication and understanding" problems”. In this
article I am going to outline some ways to fix these root
causes by looking at the re-examining the problem and
pursuing 2 primary goals:
DOCUMENTATION
DOCUMENTATION
I was working with a company a few
years ago who kept asking about
documentation, so I wanted to find
out the root cause of this issue. I
asked them
They proceeded to tell me about the
MRD, the PRD, the project charter,
the test scripts, the test results,
the architecture diagram, and all the
other artifacts they put together.
After we laid out all the
documentation they "needed", I began
to ask one by one,
About half of the documents had no
"known customer".
So of course I asked the question,
they exclaimed.
So I asked the question
As far as the other half of the
documents that actually had
customers, we went around and did
some basic customer development.
Each stakeholder group we would ask
"Who is the customer of
this document?"
"What do you do today?"
"If no one is reading
these documents, and no
one wants these
documents, why are we
creating them?"
"Because we need them!"
"To whom is this documentation
providing value? If we don't
know who the customer is, and no
one is reading them, it appears
they have no value, and you do
not, in fact, need them."
"What specifically do you need to
know from this document, and how
can we better help you with the
information you need."
40 pages transformed into into 5 pages with simple and
powerful techniques: create what the customer needs and
create only what is valuable.
Most of the time the documentation processes
are from another era, created to fulfill
different needs. So we end up with the
burden of creating documents long after the
documents have lived their useful lives.
Additionally, there are never enough people helping
with the documentation effort to make it sustainable.
Sure, every once in awhile when there is a change of
leadership or a process audit, we get "All hands on
deck" to create/update documents. But after the storm
has passed, things go back to normal, and the bloated
documents that provide no value are rotting in
Sharepoint or on some network share drive once again.
The root cause of this is that documentation is not
seen as a first class deliverable. Another way to say
it is to say that documentation only gets attention
after EVERYTHING ELSE. After requirements, after
coding, after testing, after everything else we do, we
look at documentation. Few projects have enough time,
money, and people. The window of time for
documentation always gets compressed near the end and
never gets "done."
How enterprises perceive agile creates
confusion. As a result, you have a lot of
companies who think agile = no documentation.
One of the first questions I get is,
This turns into a 15 minute lecture about
pull, and value, and dispelling the myth that
agile = "no documentation"
"Agile says no documentation, how do we
document things".
Which brings me to the premise of this
article: What is the real problem we are
trying to solve?
We are trying to solve a
communication problem.
We want to spread and transfer
knowledge as effectively as possible.
We are trying to solve an
understanding problem.
We want to ensure that the
understanding is consistent from one
person to the next... that they are
all "reading from the same sheet of
music" as it were.
When we examine documentation from the
perspective of communication and
understanding, we can now think of better
ways to solve these problems. We can think
of solutions other than pages and pages of
hand-created documentation.
This starts by understanding out who the
audience is for a document and what the
audience wants from the document. You find
that out by asking. Avoid creating single
overloaded documents to serve everybody.
Instead, create single purpose documents to
serve a single audience. This helps you to be
able to update and change documents as needs
change and as processes change.
Streamline and figure
out what you really
need to create
When documentation is only the responsibility
of an unlucky few, you will not be successful
in creating and updating high quality
documents. In the case of having people pair
together, have one person write code while the
other person documents.
Make documentation a
cross-functional
responsibility
Automated documentation that gets created
with each build is much more likely to stay
updated. Use tools like javadocs, doxygen,
and swagger to automate creation of
timestamped documentation, controlled and
can stand up to an audit.
Use tools to automate
documentation
In 2014, video is fast and easy to create, and
provides a much richer communication channel
than written documentation. A 5 minute
explainer video can take the place of a 10 page
document. It’s much more likely that people
will watch it, it's easy to change and update,
and it is easily shared. Use screencasts and
explainer videos to remove some of the burden
of documentation.
Another overlooked
technique for creating
and sharing understanding
is video