►
Description
Speaker: Geoffrey Cline
The Kubernetes community uses static site generators (Hugo+Docsy, Mkdocs, etc) and markdown to radically simplify managing open source project docs. I'm a huge fan. Some issues remain complex, namely managing different content versions, providing high quality search, and maintaining diagrams. A discussion of these problems, and a look at potential solutions.
A
I'm
really
excited
about
open
source,
technical
writing
at
Amazon,
so
I
previously
I
came
from
legal
writing
which
huge
change
come
to
the
open
source
Community,
but
I
really
love
our
platform.
I
like
authoring
in
markdown
I
like
using
static
site
generators,
it's
cool
that
the
these
skills
are
generalizable
to
other
platforms.
The
source
is
highly
readable,
easy
to
author.
It's
fast
to
build
and
deploy
I
like
using
git
to
manage
docs
compared
to
like
every
other
version
control
system,
especially
older
things,
for
managing
Word
documents.
A
But
there
really
are
some
challenges
around
like
open
source
stocks
in
the
platforms
that
I've
I've
really
had
challenges
with
myself
and
I
haven't
been
able
to
find
good
solutions
for
the
so
there's
versioning,
which
is
how
do
you
know
if
the
docs
you're
looking
at
match?
What's
going
on
with
your
cluster
there's
search,
which
is
self-explanatory
and
finally,
there's
diagrams,
which
I
think
is
something
we
should
absolutely
be
using
more
to
explain,
Concepts
to
users,
so
getting
started
with
versioning.
A
So,
taking
a
look
at
like
the
two
platforms
that
I'm
familiar
with
there's
Hugo
and
doxy,
which
is
what
we
use
for
K
website
and
it's
interestingly
The
Arc,
archived
content
flag
is
build
wide,
which
was
really
surprising
to
me,
and
the
like.
The
Hugo
nordoxy
have
specific
guidance
on
how
to
version
your
content.
A
Mk
docs,
specifically
with
the
mic
plug-in
I,
was
really
pleasantly
surprised
by
the
static
site
generator.
It
has
the
best
user
experience
for
managing
different
versions
of
content.
It's
it's
more
opinionated
by
far
than
Hugo
and
there's
a
little
bit
more
of
a
risk
of
Abandonment.
But
if
you,
if
you
take
a
look
here,
this
is
wonderful
to
me
that
you
can
list
the
currently
deployed
versions.
A
So
taking
a
look
at
how
two
sites
do
it
right
now,
you
can
see
the
main
kubernetes
site.
Does
it
using
subdomains,
which
requires
more
like
infrastructure
automation,
to
do
the
DNS
records
and
to
make
a
new
netlify
site
for
each
version
which,
for
smaller
projects
in
the
kubernetes
space,
probably
isn't
very
feasible?
A
So
you
can
see
K
native
below
they
just
do
different
paths
on
the
same
domain,
which
is
a
lot
easier
to
manage.
But
then
you
have
like
the
same
host
is
hosting
all
of
them
and
then,
when
you
change
a
version
from
like
the
from
the
current
version
to
the
old
one,
then
you
have
to
change
all
the
URLs.
Well
at
least
the
build
tool
has
to
so
my
recommendations
for
if
you're
having
challenges
with
versioning
a
open
source
stock
site
is
for
small
projects.
A
Don't
think
about
it
too
much
at
the
beginning,
wait
until
there's
a
breaking
change
and
then
for
many
small
sites,
it's
appropriate
to
do
just
plain
markdown
files,
and
then
there
they
live
alongside
the
code.
They're
version
the
same
way,
usually
with
Git
tags
and
then,
as
your
project
grows
in
complexity,
I'd,
take
a
strong
look
at
using
the
mkdocs
mic,
plugin
with
paths
working
on
the
same
domain
and
then
start
thinking
about
doing
pre-release
stocks,
and
that
means
pre-release
stocks
means
when
you
do
like
a
PR
against
main.
A
It
goes
to
a
pre-release
or
preview
version
instead
of
the
currently
released
version.
And
then,
when
you
release
a
new
version,
the
docs
get
promoted.
I
think
that's
that's
a
good
pattern
and
then,
as
projects
get
into
higher
complexity
like
you're,
using
a
lot
of
short
codes
or
custom
layouts,
that's
when
you
should
start
considering
deploying
different
versions
on
different
subdomains.
A
There
are
some
unresolved
problems
with
versioning
docs
content.
It's
hard
to
link
between
different
versions.
It
doesn't
seem
like
there's
an
accepted
best
practice
on
how
to
do
this.
For
example,
like
K
native
I
showed
they
do
they
use
mpdocs,
but
they
have
their
own
custom,
build
script
and
a
lot
of
a
lot
of
projects
have
that
also
I'd
like
to
avoid
that
kind
of,
like
everyone
figuring
out
their
own
way
to
do
it
and
then,
additionally,
as
we'll
get
into
next,
it's
hard
to
search
across
different
versions
of
the
docs.
A
So
here
you
can
see
K
native,
which
uses
lunar
I,
think
it
has
a
good
UI
and
importantly,
you
can
see
faded
out
the
version
selector.
Whatever
version
you
have
selected,
that's
the
version
of
the
docs
you're
searching
so
kubernetes.
Interestingly,
even
when
you
have
a
prior
version
selected,
the
search
results
are
always
from
the
latest
version,
and
then
additionally,
this
was
surprising
to
me.
The
search
UI
varies
by
browser
which
I
was
surprised
by
and
finally
a
site
I've
worked
on
Carpenter.
A
This
is
probably
embarrassing
for
me
to
say
an
example
of
what
not
to
do
since
I
said
this
set
this
up.
You
can
see
in
the
search
results.
There's
every
single
version
is
returning
its
own
search
result,
and
this
has
proved
to
be
confusing
for
users,
so
recommendations
for
search
again
I
was
very
pleasantly
surprised
by
how
well
mkdocs
handleds
this
it's
easy
to
manage
the
Statics.
A
A
One
thing
I,
that's
only
50
related
that
I
want
to
talk
about,
is
GitHub
code
search,
so
I
was
surprised
to
learn
from
AWS
support,
Engineers
that
when
they're
searching
for
kubernetes
related
information
a
lot
of
times,
the
first
place
they
go
is
the
GitHub
search,
and
this
allows
them
to
search
across
many
different
docs
sites.
All
at
once,
like
the
AWS
docs
are
published
on
GitHub,
so
are
the
Azure
docs
and
then,
of
course,
the
kubernetes
source.
Markdown
files
are
also
so
I.
This
is
an
interesting
idea.
A
A
So
that's
a
bit
about
search
I
am
blasting
through
these
slides.
Please
forgive
me
for
being
a
bit
nervous.
The
so
next
thing
I
want
to
talk
about
is
diagrams.
This
is
something
I
strongly
feel
like.
We
should
have
more
of
I
think
the
reason
we
don't
right
now
is
because
they're
frankly,
very
difficult
to
update
and
Translate
and
additionally,
a
lot
of
the
tools
we
use
are
closed
source
and
are
incompatible
with
how
we
do
things
using
static
site
generators.
A
So,
for
example,
a
lot
of
the
images
on
the
K
website
right
now
are
SVG
files
and
those
I
mean
I.
The
some
of
the
tools
are
expensive
and
not
cross-platform,
and
if
you
take
a
look
at
this
diagram
here
like
if
I
were
to
go
and
open
that
like
where,
where
is
the
source
file
for
this,
do
I
have
the
proper
fonts
installed
so
that
it
can
be
really
difficult
to
update
these
things
and
then
translate
them
like
I
said
before
one
one
solution
to
this
is
mermaid,
which
is
a
domain
specific
language.
A
Surprisingly,
it
is
already
integrated
into
our
Hugo
build
process
in
a
feature.
I
really
like
is
that
the
diagrams
are
accessible
to
screen
readers
which,
if
you've
ever
had
to
do
alt
text
or
images
before
can
be
a
big
pain
to
do
that
for
diagrams,
as
you
are
like
kind
of
like
re-explaining
everything
again
so
great
feature,
these
These
are
accessible
to
screen
readers
they're
also
easier
to
update
and
translate.
However,
a
downside
is
that
it's
difficult
to
customize
the
appearance.
So
here
is
an
example
of
both
mermaid
source
and
an
output
diagram.
A
So
you
can
see
in
the
left.
This
goes
in
line
with
markdown
I
think
the
first
part
fairly
fairly
intuitive.
In
terms
of
your
just
kind
of
defining
simple
relationships
between
different
chart
elements,
it
is
a
bit
inconvenient
to
have
to
paste
in
these
class
definitions
that
do
the
colors
and
line
fills.
A
That's
okay,
though,
and
then
you
can
see
that
it
generates
a
this
pretty
diagram
here
on
the
right,
but
the
problem
is
that
this
once
it
generates
a
diagram
on
the
right,
you
can't
like
drag
things
around
to
rearrange
them
you're
stuck
with.
However,
mermaid
generates
it
which
can
be
frustrating
if
it's
kind
of
doing
the
layout.
You
did
not
have
in
your
own
mind
so
for
recommendations
for
mermaid
I,
really
think
we
should
be
using
mermaid
more.
You
can
try
the
quick
start
from
the
kubernetes
docs
contributor
guide.
A
So
so
in
conclusion,
as
I,
which
I'm
in
conclusion
I
was
really
pleasantly
surprised
by
MK
docs
I've
used
Hugo
way
more
in
my
open
source.
Tactical
writing
experience.
It
does
provide
a
much
better
experience
for
versioning
and
search.
Those
are
two
complex
and
important
features
of
OSS,
docs
and
finally
use
mermaid
for
diagrams
I
was
hoping
at
this
point
to
transition
into
more
of
like
a
docs
contributor
discussion,
but
I
realized.
This
room
format
is
not
super
conducive
to
that.
A
It's
heavy
so
I,
don't
think
there's
so
obviously
the
dream
of
markdown
is
that
we
would
be
able
to
just
feed
the
same
markdown
files
into
a
different
static
site,
generate
different
sex
I
generated
and
get
the
same
thing,
but
there's
a
lot
of
kind
of
customized
content
and
some
things
that
are
like
the
The
Meta,
the
head,
the
header
or
the
metadata
is
a
bit
different.
So
I
think
it
would
be
a
huge
challenge.
A
I
think
for,
like
my
recommendation,
is
for,
like
smaller
projects,
consider
using
MK
docs,
but
something
that's
truly
as
large
as
the
main
kubernetes
website
stick
with
Hugo,
intoxic
and
I.
Think
there's
just
there's
some
improvements.
We
can
make
like,
perhaps
figuring
out.
What's
going
on
with
the
differing
search,
UI
and
then
see.
If
there's
a
way,
we
can
provide
a
better
A,
Better
Way
for
people
to
search
a
specific
version
of
the
docs
so
for
K
website,
I
prefer
just
kind
of
incremental
improvements
and
then,
if
you're,
a
smaller
project,
definitely
check
out
mkdocs.
C
So
I've
seen
a
couple
different
OSS,
docs
setups,
where
they
handled
versioning.
One
way
is
they
had
like
a
whole
different
set
of
directories,
so
you're
in
the
same
Branch
there's
like
five
different
direct
folders
and
each
of
those
folders
has
the
different
version
of
the
docs.
Yes
and
then
the
other
way
is
to
have
them
on
separate
branches.
So
just
the
whole
thing's
on
you
go
to
a
different
branch
and
you've
got
a
whole
new
set
of
docs.
C
A
So
I'm
going
to
pull
up
some
slides
that
are
slightly
relevant,
so
there's
to
recap:
Chris
Chris's
question
is
about
the
different
ways
of
handling
where
you
store
the
different
versions
of
content.
So
kubernetes
does
it
in
different,
like
previous
tags,
which
I
think
is
the
which
makes
sense
for
larger
projects,
but
it
can
like,
if
sorry
I'm,
struggling
to
collect
my
thoughts
here.
A
If
you,
if
you
take
a
look
at
the
bottom
one
there
it's
on
the
same,
it's
on
the
same
host,
so
the
default
Search
scope
will
be
everything
on
that
that
domain
that
host,
and
so,
unless
you
properly
configure
the
search
to
show
like
just
I,
only
want
this
version
1.6.
It
will
return
results
from
everything.
That's
in
that
build
so
kubernetes
that
works
like
things
are
on
different
domains.
A
A
That
is
an
excellent
question.
I
did
not
I
have
to
admit
that
I,
the
a
tentative
fourth
one
that
I
was
considering
adding
to
this
was
different
languages,
because
that
is
and
that
that's
different
versions,
but
it's
also
truly
an
entirely
other
Beast
I
have
I
have
not
worked
with
off
like
authoring
content,
for
that
is
translated
or
published
in
a
different
version.
Very
much,
but
I
I
suspect
that
a
lot
of
these
same
issues
exist
for
different
languages.
A
A
E
A
Think
as
your
as
your
audience
expands
and
the
number
of
pages
you
have
expands,
that's
when
you
should
start
using
a
static
site,
generator
and
so
I
think
the
the
easiest
one
I
think
to
get
started
with
is
is
MK
docs,
because
it's
kind
of
like
it's
integrated
with
the
theme
it's
very
designed
for
documentation.
It
has
a
great
search
built
in
so
once
you
kind
of
ready
to
move
past
the
plane,
markdown
file
stage,
I
take
a
look
at
mkdocs
and
then,
as
you
grow
in
complexity,
you
start
using
different
versions.
A
Add
on
the
mic,
plugin
for
managing
different
versions
and
then,
as
you
reach,
a
very
high
level
of
complexity.
Your
doc
site
is
huge.
You've
got
many
different
versions
going
on.
That's
when
I
take
a
look
at
the
Google
programmatic
search
engine
and
I'd
switch
to
using
that
instead
of
the
MK
docs
built-in
search
engine,
because
that
it
works
better
for
larger
volumes
of
content.
E
What
documentation
do
we
have
or
do
you
think
we
would
need
for
folks
to
start
adopting
these
because
I'm
from
the
contributor
comms
group,
where
we
focus
on
making
sure
that
folks
understand
tools
that
they
can
use
and
things
that
are
going
on
in
the
project
and
stuff?
So
I'm
wondering
if
there
are
things
we
could
do
to
help.
A
A
So,
if
you
use
that
same
language,
hopefully
they
will
naturally
find
the
docs
site
through
search
so
yeah.
So
you
you
can,
when
you're
building
a
new
Doc
site,
you
can
either
like
focus
on
the
things
you
want
users
to
be
able
to
do,
but
I
think
it's
a
better
approach
to
try
and
understand
what
people
are
currently
looking
for.