►
Description
Continuously Delivered Documentation - Matthew Casperson, Octopus Deploy
To give our customers the easiest onboarding solution possible, we recently created a selection of 80 guides that documented the integration between 5 or so common technologies required to complete a deployment. This was great for customers, who could read documentation highly targeted to their own technology stack, but presented us with many problems. How could we know that our guides were accurate? How could we keep screenshots up to date? And how could we do all this without a huge team dedicated to continually manually reviewing each guide? By bringing common DevOps practices like automated tests, infrastructure as code, and continuous deployments, we have maintained 80 guides, hours of screencasts, and thousands of screenshots with a team of 2. Our process was documented at https://octopus.com/blog/devops-documentation, and the proposed session will discuss this journey.
For more Continuous Delivery Foundation content, check out our blog: https://cd.foundation/blog/
A
A
A
We
also
realized
our
documentation
had
a
number
of
other
limitations
as
well.
We
spend
a
lot
of
time
on
the
user
interface
in
our
product.
It's
something
that
we
spend
quite
a
bit
of
effort
or
divide
a
bit
of
effort
into
refining,
but
the
documentation
itself
didn't
include
a
lot
of
screenshots,
and
this
was
mostly
because
the
screenshots
could
become
out
of
date
very
quickly
and
more
so
when
you
realize
that
our
product
was
released
much
faster
than
our
documentation.
So
our
product
is
released
depending
on
the
particular
platform
that
you're
on.
A
The
documentation
itself
was
also
not
verified,
particularly
often
so
it
tended
to
be
written
once
by
a
developer
added
a
new
feature,
and
at
that
point
it
was
up
to
the
customer
support
team
or
the
customers
themselves
to
reach
out,
and
let
us
know
if
there
was
any
discrepancy
between
the
documentation
and
the
product.
So
it
was
a
very
reactive
process
offered.
Documentation
would
be
out
of
date
for
months,
if
not
years
before,
anyone
noticed,
and
obviously
this
was
not
ideal
and
not
providing
our
customers
with
the
best
experience.
A
We
also
noticed
that
writers
have
been
left
out
of
the
dev,
whatever
ops
movements,
so
you
have
devops
dev
test
ops,
dev
set
ups.
A
lot
of
these
movements
are
about
streamlining
and
integrating
the
process
of
delivering
software,
but
writers
really
had
no
hook
into
this.
They
were
off
to
the
side.
They
were
left
to
react
to
the
changes
in
the
product
and
and
do
the
best
they
could,
but
they
certainly
weren't
integrated
and
we're
missing
out
on
a
lot
of
the
benefits
that
the
devops
and
its
derivatives
tended
to
provide.
A
We
wanted
to
have
plenty
of
screenshots
and
videos.
The
idea
that
we
would
have
to
describe
a
user
interface
in
words
and
then
leave
it
up
to
the
user
to
mentally
jump
from
the
words
they
were
reading
in
the
documentation
to
the
pictures
they
were
seeing
on.
The
screen
was
something
we
wanted
to
avoid.
If
it
was
all
possible
by
including
screenshots
and
video,
we
could
ensure
that
our
documentation
demonstrated
our
diagrams
exactly
in
what
we
expected
the
users
to
be
interacting
with.
A
Perhaps,
most
importantly,
though,
we
had
a
very
small
team
to
dedicate
to
this,
so
the
initial
implementation
was
something
that
had
to
be
delivered
with
two
people
and
once
the
documentation
was
done,
the
whole
system
had
to
be
maintained
by
myself
in
my
spare
time.
So
we
had
very
few
resources
that
could
we
could
lean
on
to
deliver
this.
A
The
solution
that
we
came
up
with
went
on
many
of
the
proven
ideas
that
had
been
established
in
separate
processes
that
individually
worked
quite
well,
but
had
never
really
been
linked
together
before
so.
We
realized
that
our
focused
documentation
needed
a
lot
of
reusable
content,
and
so
this
idea
is
borrowed
heavily
from
component
content
management
systems
where
content
is
built
up
from
individual
pieces
of
reusable
content.
A
We
needed
to
verify
that
the
procedures
we
were
documenting
were
still
valid
and
we
did
this
through
browser
automation,
and
so
this
has.
This
has
been
proven
through
techniques
like
end-to-end
testing,
where
the
the
application
under
test
is
actually
interacted
with,
as
if
an
external
external
user
was
using
it.
But
in
our
case
the
the
user
is
actually
an
automated
piece
of
software.
That's
clicking
on
the
buttons
and
filling
in
all
the
all
the
text
boxes.
A
So
I
just
want
to
jump
into
the
actual
documentation
that
we've
created
with
this
process.
So
you
can
see
what
the
end
result
looks
like
so
on.
Our
company
homepage
is
octopus.com
down
the
bottom.
We
have
a
tutorial
builder.
These
drop
down
lists
here
are
that
left
to
right
selection
of
technologies,
that's
that
we
referred
to
in
previous
slides,
and
so
the
idea
here
is
that
a
customer
can
come
in
select
their
version
control
the
language
they're
developing
in
their
build
server.
A
The
target
and
package
repository
and
get
a
detailed
and
customized
tutorial,
and
so
that's
the
tutorial
here,
and
so
this
is
designed
to
be
read
from
top
to
bottom.
There's:
no
expectation
that
the
reader
has
to
understand
the
process
before
they
started
and
there's
no
jumping
between
individual
pieces
of
documentation
to
get
the
overall
process
I'll
actually
dive
into
the
the
test
vms
that
we
created
out
of
this
later.
But
I'll
start
with
this
video
walkthrough,
and
what
you
can
see
here
is
a
a
video
capture
of
the
process
being
verified
by
an
automated
script.
A
So,
if
you've
ever
used,
tools
like
webdriver
before
you'll
know
that
typically,
the
interactions
with
the
browser
tend
to
happen
silently
and
automatically.
So
if
a
button
was
clicked,
it's
like
a
ghost
hand,
just
reached
up
and
clicked
it
there's
no
visual
indication
that
anything
is
about
to
happen
in
ours.
A
There
are
some
customizations
here
to
list
the
name
of
the
the
ci
system
that
we're
interacting
with,
but
apart
from
a
few
small
changes,
all
this
content
is
reused
everywhere
that
we
need
it.
The
other
thing
to
note
is
the
highlights
in
these
screenshots,
so
these
green
boxes
here
have
been
added
automatically
as
part
of
the
process,
and
we
use
these
as
a
way
of
calling
out
the
widgets
that
the
end
user
expected
to
interact
with.
A
So
when
we
say
you
click
the
api
keys
tab
and
then
you
click
on
the
api
key
button.
These
links
or
widgets
have
been
highlighted
in
screenshots,
so
there's
no
translation
of
words
to
images
that
the
end
user
is
expected
to
do,
and
the
the
call
out
or
the
representation
of
the
process
that
the
end
user
is
expected
to
go
through
is
very
clear
between
the
text
and
the
highlighted
images.
A
A
So,
behind
the
scenes
we
have
a
custom
application
that
uses
webdriver
driven
by
cucumber
and
the
gherkin
language
it
exposes
to
automate
the
interaction
with
browsers.
One
of
the
things
we
realized
was
quite
important
in
this
process.
Was
that
a
lot
of
the
pro
a
lot
of
the
the
scripts
had
shared
steps,
and
so
we
have
steps
like
this
that
allow
individual
guides
to
reuse
shared
steps
and
processes.
A
That's
very
much,
not
true
in
practice
and
digging
up
the
particular
button
or
link
that
you
need
to
interact
with
often
requires
fairly
complex,
x
parts
like
this
one
here
so
to
keep
the
scripts
readable.
We
introduced
the
idea
of
aliases,
which
are
really
just
key
value
pairs
on
the
left.
Here
we
have
a
nice
user-friendly
name
and
on
the
right
here
we
have
this
failure
choose
x
path.
A
A
The
gherkin
language,
that's
exposed
by
the
cucumber
library,
is
about
as
close
to
plain
english
as
you
can
get
in
terms
of
automated
scripts,
and
so
we
use
this
in
conjunction
with
the
the
aliases
to
provide
scripts
that
read
very
naturally
from
top
to
bottom,
and
so
these
these
words
here
and
the
quotes
are
all
the
aliases,
and
this
is
abstracting
away.
The
complex
x
paths
that
that
we
might
need
to
use
in
order
to
find
the
widgets,
and
so
this
particular
script
here
is
clicking
on
a
link.
A
A
So
if
you're
running
these
sequentially,
you
would
eventually
find
there's
just
not
enough
hours
in
the
day
to
actually
run
all
your
tests,
but
by
using
github
actions
we
can
actually
scale
horizontally
almost
infinitely,
and
so
in
our
case
we
run
many
of
these
tests
in
parallel
and
the
overall
time
it
takes
to
to
run
all
our
scripts
is
only
about
90
minutes.
We
just
have
10
or
so
running
at
once.
A
And
so
this
is
really
useful
because
it
means
we
can
provide
people
with
an
end-to-end
guide
that
they
can
follow
for
themselves.
And
we
can
also
link
them
off
to
one
of
several
vms
that
actually
show
everything
configured
for
them
and
they
can
come
in
here
and
play
around
and
snapshot
and
reverse
as
they
need
to.
And
it's
a
very
convenient
way
of
trialing
the
software
without
committing
to
it
or
or
setting
anything
up
on
your
local
machines.
A
A
So
the
main
purpose
of
our
automated
scripts
hasn't
actually
been
to
test
the
product,
but
processes
and
the
technologies
involved
are
very
similar.
So
we
have
browser
automation
through
webdriver.
We
have
ci
builds
through
our
github
actions.
We
get
a
green
tick.
If
the
process
has
been
verified,
we
get
a
red
cross
if
it
fails
and
actually,
if
we
triggered
these
builds
or
these,
these
verification
scripts
on
on
a
git
commit,
or
we
relied
on
the
fact
they
were
green
before
a
production
release
went
out
the
door.
A
But
this
leaves
us
with
a
question
of
what
is
the
relative
number
or
relative
amount
of
documentation
compared
to
unit
tests,
and
that
comparison
no
longer
makes
sense.
Documentation
is
independently
valuable
and
the
idea
that
ui
tests
are
slower
and
perhaps
less
reliable,
gets
turned
on
its
head
when
you
realize
that
using
these
scripts
and
these
processes
to
automatically
generate
new
screenshots
and
verify
documentations
is
actually
one
of
the
fastest
and
most
reliable
ways
of
doing
it.
A
So
this
the
idea
that
ui
tests
need
to
sit
at
the
top
of
the
pyramid
and
have
relatively
less
than
unit
tests
really
needs
to
be
challenged.
And
I
think,
if
you
embrace
this
strategy,
you'll
end
up
more
with
an
hourglass
shape,
where
a
unit
tests
that
value
for
data
for
developers
and
ui
tests
can
be
used
to
add
value
for
the
documentation
team.
A
A
We
have,
I
mean
close
to
half
a
million
words.
We
have
24
hours
of
video
and
10
000
images
across
these
guides
and
all
of
them
are
maintained
by
me
and
my
spare
time.
There
is
no
documentation
team
that
is
maintaining
these
builds
or
these
documents,
and
so
all
of
this
has
a
very
low
cost
in
terms
of
the
personnel
that
have
to
maintain
it.
A
A
This
wasn't
a
particular
goal
that
we
had
when
we
were
writing
the
guides,
but
it
has
been
a
nice
little
side
benefit,
and
we
also
find
now
that
we
are
quite
quick
and
proactive
in
updating
our
documentation
as
the
platforms
that
we
document
are
updated.
So
one
example
recently
has
been
jenkins
moved
from
tables
to
divs.
In
its
user
interface
and
although
the
the
effect
of
that
was
fairly
subtle
for
end
users,
we
could
we
could.
A
We
could
reference
the
new
user
interface
out
documentation
within
the
space
of
of
two
weeks,
because
each
of
our
guides
is
rebuilt
and
verified
within
within
two
weeks,
and
I
have
here
a
little
quote
from
one
of
our
customers
who
had
some
feedback
for
our
documentation,
and
it
seems
like
that
that
the
documentation
is
doing
its
job
in
helping
people
achieve
their
end
results,
and
the
best
news
is
that
all
of
the
technology
I've
shown
here
is
free.
So
the
link
here
this
is
the
guides.
A
Everyone
hear
me:
okay,
I
get
a
yes
or
no
in
the
chat.
Excellent.
Thank
you
I'll.
Just
answer
that
that
last
question
here
yeah.
So
the
general
process
that
we
use
is
that
we
write
the
documentation
just
as
plain
text
like
anyone
else
would
normally
write
documentation,
but
because
the
documentation
is
very
procedural
in
that
it's
describing
that
click.
This
click
that
enter
text
here.
A
What
we
find
is
that,
because
that
that
procedure
is
automatically
tested
as
part
of
that
those
scripts
that
we
saw
earlier
in
the
presentation,
if,
like
if
a
step
in
that
test,
fails,
we
we
almost
certain
that
the
documentation
has
to
be
updated.
So
maybe
a
button
name
has
changed,
for
example,
and
so
what
will
happen?
A
A
Do
we
collect
feedback
about
the
docs?
Are
we
we
do?
I
don't
actually
have
any
stats
that
I
prepared,
but
some
of
the
other,
so
we
do
collect
some
anecdotal
feedback
and
that's
been
mostly
positive,
and
I
think
the
other
thing
that
we've
found
is
that
they're
fairly
well
trafficked
compared
to
the
the
bulk
of
our
documentation,
which
doesn't
actually
use
this
process.
A
A
A
Right
there
so
the
time
from
a
git
merge
to
master
and
deploy
yeah.
So
that's
a
that's
a
good
point.
Brian
one
of
the
things
that
we
did
consider
was
perhaps
tying
the
the
running
of
those
tests
to
get
mergers
today,
they're
just
on
a
schedule-
and
that's
that's
been
good
enough
for
us.
We
there's
actually
no
reason
why
we
couldn't
trigger
them
as
part
of
a
workflow
from
git,
so
perhaps
the
the
main
octopus
project,
which
obviously
we
control
the
the
git
repo
for
we
could.
A
A
The
google
rankings
were
very
interesting,
so
we
we
found
without
a
whole
lot
of
effort
on
our
part
that
we
that
we
ranked
very
well
in
long
tail
searches
and
by
long
tail
I
mean
when
you're
searching
for
like
three
or
four
different
keywords.
So
if
you
went
ahead
and
googled
kubernetes
jenkins
and
java,
for
example,
but
these
guides
well,
google
tells
me
that
these
guides
are
very
highly
ranked.
A
A
The
ability
to
build
those
virtual
machines
as
well
was
very
nice.
I
didn't
really
go
into
a
lot
of
detail
in
that
previous
presentation,
but
if
anyone's
interested
actually
there's
the,
we
could
probably
share
the
the
code
that
we
used
to.
Actually
build
up
those
virtual
machines,
it's
a
process
of
using
a
vagrant
and
a
couple
of
aws
bare
metal,
virtual
machines
that
allow
us
to
run
the
hypervisors
like
hyper-v
and
virtualbox.
A
So
that's
also
been
very
good
that
it
turned
out.
We
could
just
build
these
virtual
machines
with
a
button,
click
and
reuse,
all
that
same
infrastructure
that
we'd
had
for
the
for
the
documentation
and
that
that
was
really
nice.
That's
it's
a
nice
little
side
benefit
and
it's
a
good
thing
to
demo
to
people
who
just
want
a
quick
way
of
sampling,
the
the
workflow
that
you've
documented.
A
A
Building
up
these
getting
started
guides
was
a
something
that
was
discussed
quite
often,
but
I
just
don't
think
we
ever
managed
to
get
around
to
it,
because
once
we
looked
at
the
resources
that
would
be
required
to
to
actually
do
it
and
and
deliver
it
for
years.
At
a
time
it
just
became
quite
daunting.
A
Oh
okay,
sorry
I
have,
I
was
doing
it
wrong,
looks
like
I
have
a
few
people
have
answered
in
the
polls,
so
our
google
rankings
and
important
consideration
for
your
documentation.
It
looks
like
71
say
yes
yeah,
and
we
found
that
too.
It's
I
mean
it
was.
It
was
certainly
nice
to
be
able
to
just
to
have
documentation
and
point
people
to
it
for
the
purpose
of
support,
but
certainly
generating
that
traffic
coming
in
allowed
us
to
add
a
lot
more
value
to
our
documentation.
A
A
You
know
a
weekly
basis,
sometimes,
but
actually
now
we
do
so.
This
testing
process
has
really
has
really
allowed
us
to
to
gain
that
confidence
and
I'd
be
quite
happy
to
point
people
at
our
guides
and
say
that
yeah
as
of
two
weeks
ago,
we
we
know
those
guides
work,
so
the
writing
teams
make
use
of
ci
cd
platforms
today
looks
like
an
even
split
so
that
does
match.
A
With
my
experience,
I
think
writing
teams
are
getting
more
integrated
into
those
platforms,
but
the
platforms
are
still
very
developer,
oriented
from
what
I
can
tell
and
if
you
want
to
have
a
ci
cd
platform,
creating
docs,
it's
very
much
on
you
to
to
script
all
that
up.
So
I
think
that
matches
with
my
experience.
A
What
we'd
find
is
that
the
developers
would
write
the
feature
it
would
be
pushed
into
master
released
and
then
at
some
point
in
the
future,
someone
would
come
back
and
write
some
documentation
for
it,
and
even
then
the
documentation
would
sit
there
for
a
year
or
two
slowly
going
stale
until
a
customer
actually
pointed
out
that
it
was.
It
was
now
out
of
date.
A
Right,
so
the
writing
teams
include
a
lot
of
screenshots.
It
looks
like
almost
everyone
said.
Yes,
that's
actually
surprising.
I
most
of
the
teams.
I've
worked
in
have
had
policies
that
say
you
really
shouldn't
include
screenshots
and
they
kind
of
encourage
people
not
to
do
it.
So
that
is
that's
interesting
feedback,
but
I
love
screenshots.
I
I
really
hate
having
to
translate
the
the
words
in
the
documentation
to
to
what
I
see
on
the
screen.
So
I
think
screenshots
are
incredibly
valuable.
A
So
I
think
we're
coming
up
on
our
time
here,
I'd
like
to
thank
everyone
for
for
joining
and
feel
free
to
reach
out
to
me
on
twitter.
If
you
have
any
questions
everything
you've
seen
here
is
free
and
open
source,
so
I
can.
I
can
certainly
give
it
out
and
provide
examples
if,
if
anyone
wants
to
take
this
a
little
bit
further
yeah,
so
thank
you
all
for
joining
and
I
hope
everyone
enjoys
the
rest
of
the
of
the
cd
conf.