The document discusses why documentation is needed even for those who prefer working software over documentation. It argues that documentation provides context for new team members and helps demonstrate that the work being done is understood. The document recommends creating lightweight documentation like diagrams, maps, and wikis to depict the major components and flows of the software system at a high level, as well as more detailed documentation for complex or infrequently used areas. It advises selecting a core set of documentation to maintain and focus on documenting the why rather than just the what.
1 of 10
Download to read offline
More Related Content
Why you need more documentation
1. Why
you
need
more
documenta/on
Even
if
you
favour
working
so8ware
over
comprehensive
documenta/on
Andy
Longshaw,
Advanced
Legal
Ltd.
(andy.longshaw@advancedcomputerso8ware.com
or
andy@blueskyline.com)
some
Please
keep
ques/ons,
booing
and
roEen
fruit
/ll
the
end
2. Why
do
you
need
documenta/on?
(1)
≒ Because
I
dont
know
what
youre
doing
Who
the
hell
am
I?
New
starter
on
the
team
≒ What
are
the
main
parts
of
the
system?
≒ Wheres
the
simple,
big
picture?
[pause,
blank
looks]
≒ I
have
been
here
quite
a
few
/mes
Sheltering
manager
≒ I
need
a
vague
idea
of
whats
going
on
≒ I
need
a
warm
fuzzy
feeling
that
you
know
what
youre
doing
3. Why
do
you
need
documenta/on?
(2)
≒ Because
you
dont
know
what
youre
doing
Some
bits
are
clear
but
other
bits
are:
fuzzier,
older,
broader,
outside
your
domain,
etc.
I
have
been
here
quite
a
few
/mes
as
well
4. What
documenta/on
do
you
need?
≒ NOT
200-足page
specs
≒ A
clean,
well
understandable
codebase
with
clear
domain
abstrac/ons
at
its
heart
is
a
good
start
but
beyond
that
≒ Mostly
pictures
Maps
of
the
world,
which
could
be
hand-足drawn
Plus
some
more
detailed
documenta/on
of
trickier
bits
like
complex,
infrequently
needed
con鍖g
≒ wiki
is
usually
good
for
this
5. Maps
of
your
world
(1)
≒ Tribal
Maps
Meaningful
to
the
na/ves
Or,
more
usefully,
Fred
met
a
dragon
here
once.
It
was
de鍖nitely
a
dragon,
not
a
/ger
and
he
was
able
to
get
away
by
6. Maps
of
your
world
(2)
≒ Di鍖erent
levels
+
di鍖erent
info
Contours,
major
towns,
etc.
≒ In
the
so8ware
world
≒ Simon
Brown
Context,
Containers,
Components,
Classes
≒ For
bigger
or
more
complex
systems,
can
split
down
into
Viewpoints
and
Perspec/ves
IEEE
1471
or
Rozanski
&
Woods
Especially
if
there
are
a
lot
of
NFRs
and/or
lots
of
things
outside
the
so8ware
7. How
does
this
work
in
prac/ce?
(1)
≒ Choose
a
core,
non-足vola/le
subset
If
you
cant
decide
on
this
then
maybe
you
have
more
problems
than
a
lack
of
lightweight
docs
Be
selec/ve!
S/ck
them
on
the
wall
Keep
them
up
to
date
(see
Be
selec/ve!)
≒ Otherwise
let
the
code
tell
the
detailed
what
and
document
the
high-足level
what
and
the
why
8. How
does
this
work
in
prac/ce?
(2)
≒ Environments
o8en
need
aEen/on
Maps
of
what
talks
to
what
in
DEV,
TST,
STG,
PRD
If
these
docs
are
painful
to
maintain
then
maybe
you
should
be
automa/ng
your
environment
builds
9. How
does
this
work
in
prac/ce?
(3)
≒ Ask
some
ques/ons
≒ Who
is
it
for?
≒ When
and
why
will
you/they
use
it?
≒ How
long
should
it
live
for?
Is
it
enduring
or
Is
it
transient
≒ Draw
a
diagram
to
work
out
your
thoughts
then
throw
it
away
No,
dont
leave
it
on
a
鍖leshare
to
confuse
people,
throw
it
away
損Now!
10. Dont
forget
At
the
end
of
the
day
Its
all
wri/ng
(Pragma'c
Programmers)
Except
when
its
drawing