►
From YouTube: OSS Docs and How to Scale Them: Common Themes From the CNCF Ecosystem - Celeste Horgan, CNCF
Description
Don’t miss out! Join us at our upcoming hybrid event: KubeCon + CloudNativeCon North America 2022 from October 24-28 in Detroit (and online!). Learn more at https://kubecon.io. The conference features presentations from developers and end users of Kubernetes, Prometheus, Envoy, and all of the other CNCF-hosted projects.
OSS Docs and How to Scale Them: Common Themes From the CNCF Ecosystem - Celeste Horgan, CNCF
The first interaction new users have with an open source project is documentation. Documentation is a key adoption driver for open source projects, and the professionalism, completeness, and presentation of your documentation has a dramatic impact on how your project is perceived by potential users. How do you get your project’s docs to shine? How do you set your tooling up to support you as you grow? What metrics can we use to evaluate the quality of a project’s documentation? In this talk we use data from the CNCF’s documentation assessment service to give an overview of common issues we see with open source project’s documentation and how to resolve them. She breaks out these issues by project maturity and community size, and discusses how a given project’s documentation needs change as it grows. Finally, we discuss how projects can best get documentation done as they grow, based on what we’ve seen work in various CNCF project communities.
A
A
A
Prior
to
that
for
two
years
I
was
the
staff
technical
writer
at
the
cloud
native
computing
foundation,
where
the
portfolio
of
work
that
I
did
was
supporting
all
140
plus
cncf
projects
with
their
documentation,
to
the
extent
that
a
team
of
three
can
possibly
do
that.
What
that
really
looks
like
is.
We
gave
a
lot
of
advice
to
different
cloud
native
projects
on
how
to
do
well
by
their
docs.
There
are
still
other
members
of
the
team
who
are
still
there.
Their
names
are
nathan,
waddington
and
patrice
chalin.
A
You
may
have
encountered
them
in
your
journey
in
the
cncf
and
a
lot
of
what
we're
talking
about
here
are
still
services
that
they
can
provide,
though
I
specifically
will
not
be
doing
that
for
you
in
the
community.
I
still
hold
a
couple
of
community
titles.
I
am
a
member
of
the
kubernetes
sig
docs
group,
and
I
am
also
a
member
of
the
kubernetes
code
of
conduct
committee
as
such,
please
be
wonderful
to
each
other
during
this
week,
and
especially
during
this
talk.
That
is
a
suggestion
more
than
anything
else.
A
So,
let's
talk
about
this
talk
a
little
bit
and
I
apologize
I'm
trying
to
make
sure
that
I
remember
how
much
time
I
have
left
this
talk
is
going
to
be
about
some
of
the
common
challenges
that
docs
teams
have
found.
While
we
did
cncf
docs
assessments
and
while
we
ran
cncf
office
hours
for
documentation,
we'll
talk
a
little
bit
about
what
those
are
and
how
you
can
access
them.
If
you
are
a
cncf
maintainer.
A
What
this
talk
is
not,
it
is
not
an
exist,
exhaustive
list
of
every
problem
documentation
teams
face.
It
is
not
an
exhaustive
list
of
every
solution
that
is
possible.
This
is
not
a
checklist
for
projects
looking
to
graduate
documentation
is
one
component
of
graduation
in
the
cncf
process,
and
this
is
not
a
one-size-fits-all
approach.
A
So
before
we
start
most
of
the
content
of
this
talk
was
generated
from
cncf
docs
assessments
and
cncf
docs
office
hours.
Docs
assessments
are
a
service
that
the
cncf
team
provides
to
cncf
projects
where
we
essentially
look
at
your
docs
holistically,
and
we
give
you
an
evaluation
and
a
report
based
on
where
you,
where
we
think
you
are.
It's
super
useful
one
of
the
people
that
we
worked
with
once
described
it
as
the
most
useful
service
they
had
ever
gotten
from
the
cncf.
A
So
if
you
are
a
project
maintainer,
I
highly
recommend
you
go
to
the
cncf
service
desk
and
request
this
at
least
once
in
your
journey
with
the
cncf,
the
other
thing
that
we
do
offer
as
a
documentation
team,
our
documentation,
office
hours.
We
run
these
once
a
month,
I
believe
they're,
the
first
tuesday
or
wednesday
of
the
month,
and
these
are
drop
in
if
you've
got
a
documentation.
Your
question
that
your
project
is
facing.
A
We
will
put
you
in
front
of
experience,
technical
writers,
who
can
give
you
an
answer.
Once
again,
I
no
longer
attend
those,
because
I
no
longer
work
for
the
cncf,
but
I
loved
doing
these.
When
I
was
there,
it
was
such
a
fun
opportunity
to
have
casual
chats
with
maintainers,
so
you
can
find
all
existing
appointments
for
this
on
the
general
cncf.io
calendar.
A
It's
not
the
greatest
for
actually
finding
stuff
and
I
apologize
but
they're
there
and
you
should
absolutely
drop
by
if
maybe
you're,
just
looking
to
learn
from
other
people
in
other
projects
as
well.
Okay,
so
let's
talk
about
the
extra
small
to
small
size
projects.
I
don't
want
to
categorize
these
by
how
many
maintainers
they
have,
because
there
are
very
large
and
very
mature
projects
in
the
cncf
ecosystem
that
really
only
have
like
10
maintainers.
So,
let's
talk
about
how
much
documentation
they
have.
A
A
A
A
A
A
I
there
is
a
time
for
automation.
Now
is
not
your
time.
Here
are
a
few
options
that
we
like
at
the
cncf.
We
do
have
a
hugo
netlify
starter
that
we
use
to
spin
up
projects.
It's
neither
here
nor
there
to
be
perfectly
honest
with
you.
We
like
spinning
up
projects
on
doxie
and
one
of
our
technical
writers
is
actually
a
steering
committee
member
on
the
doxie
project.
A
We
tend
to
go
for
doxy
because
it's
it's
a
little
complicated
at
first,
but
it
does
leave
a
lot
of
room
to
grow
the
company.
I
now
work
for
stripe.
Literally
last
week,
open
sourced
some
of
its
documentation,
tooling
called
mark
dock
mark
dock.
Honestly,
it's
a
little
advanced
for
a
small
project.
It's
really
best
if
you're
working
with
a
dedicated,
front-end
engineering
team.
So
it's
on
the
table.
A
A
A
To
quote
one
of
my
old
co-workers:
sometimes
I
look
for
open
source
projects
to
implement
for
my
clients,
because
I'm
an
engineer,
I'm
a
solutions
architect
and
that's
what
I
do
I
implement
for
clients
and
sometimes
I'll
find
the
perfect
project
that
does
things
perfectly
and
has
every
functionality
that
I
want,
but
the
only
documentation
they
have
is
a
read
me
and
I
have
to
implement
for
professional
clients.
So
I
don't
choose
the
project.
A
I
need
something,
that's
more
professional.
So
in
terms
of
content,
your
biggest
goal
as
a
small
project
is
moving
from
readmes
and
markown
documentation
in
your
code
repositories
to
a
website.
That
is
what
will
convince
people
that
you
are
serious
enough
and
this
project
is
well
maintained
enough
to
use
it,
and
that
is
a
part
of
what
you
need
to
do
when
you're
a
small
project.
A
The
second
thing
you
need
to
focus
on
is
not
even
necessarily
content
quality.
At
this
stage,
it
is
content
completeness
for
everything
that
gets
developed.
You
need
to
assess
and
write
the
documentation
for
it
at
least
say
that
you've
written
some.
It
doesn't
need
to
be
good,
but
you
need
to
learn
how
to
check
that
checkbox
off
a
simple
process
is
every
dev
task
always
has
to
have
a
checkbox
that
says:
did
you
do
your
docs,
yes
or
no?
A
A
slightly
more
complicated
process
that
is
very
worth
doing
at
this
stage
is
something
like
the
kubernetes
enhancement
projects,
process
or
architectural
decision
records.
Where,
for
every
code
decision
that
gets
made,
you
produce
a
little
bit
of
documentation
up
front
saying:
why
did
we
do
this?
What
is
the
structure
that
we're
trying
to
create
and
what
is
the
intended
impact
for
the
user?
A
I
love
the
kep
slash
adr
process,
especially
for
young
projects,
because
it
gets
you
used
to
the
idea
that
you
need
to
justify
your
decisions,
one
two
when
you
actually
go
to
write
your
user
documentation,
you've
kind
of
written
half
of
it
already,
and
you
can
honestly
copy
and
paste
and
that's
sweet
copy
and
paste
when
you
can
too
and
number
three.
I
think
people
mis
underestimate
how
long
lived
open
source
can
be.
A
It's
a
little
fuzzy.
This
loosely
corresponds
to
the
cncf
incubating
stage
of
projects.
At
this
point,
projects
start
to
care
a
lot
about
content
quality
about
content
organization.
They
start
to
think
about
community
and
they
start
I'm
watching
you
engineers.
You
can
start
to
think
about
automation,
but
don't
get
excited
okay.
So,
let's
talk
about
content
quality.
A
A
If
you're,
organizing
similar
pages
in
similar
ways
or
you're,
for
example,
following
a
template,
that's
also
going
to
go
a
long
leap
towards
your
content
quality
in
the
world
of
documentation.
We
call
this
parallelism
and
it
actually
aids
in
users,
understanding
and
retention
of
content
when
similar
pages
have
similar
content
structures.
A
Follow
tech
writing
best
practices.
I
will
have
a
full
slide
on
this.
After
so
don't
worry
about
I'm
not
going
to
go
into
too
much
detail
there
and
the
last
thing
is
it's
time
to
think
about
adopting
a
writing
style
guide.
But
if
you
don't
do
it
at
this
stage,
you're,
not
you're,
not
hooped,
content
organization.
So
in
the
world
of
technical
writing
we
often
refer
to
this
as
information
architecture.
A
A
There
is
an
easy
shortcut
that
works
for
almost
every
project
or
product
that
I
have
ever
been
on
in
my
10-year
career
and
that
easy
shortcut
is
organizing
pages
following
the
user's
journey,
so
for
a
lot
of
things
in
the
cncf
ecosystem,
which
are
about
like
cloud
native
deployments.
Basically,
what
this
looks
like
is
there
is
an
installation
step.
You
are
either
installing
to
an
existing
cluster
or
a
new
cluster.
A
So
your
first
chunk
of
documentation
is
about
installation.
Usually
the
next
step
in
the
cloud
native
world
is
some
sort
of
configuration
step.
Okay,
you've
installed
the
thing
now
you
wanted
to
do
something
for
you
and
you
got
to
configure
it
either
you're
applying
configurations
via
everybody's
best
friend,
yaml
or
you're,
like
passing
in
a
bunch
of
cli
flags.
So
what
are
the
different
configuration
options?
You
usually
have
to
list
them
out
and
define
them
for
somebody.
A
Usually,
the
best
thing
you
can
do
at
this
stage
too
is
provide
kind
of
recipes
for
common
configurations
like
start
to
understand
your
user
and
start
to
say,
if
you're,
this
kind
of
business,
if
you're
running
this
kind
of
cluster,
this
is
a
good
starting
point
of
configuration
for
cloud
native.
The
next
step
is
usually
deployment.
How
do
I
deploy
this
thing
into
the
wild
and
then
it's
maintenance
like
what
goes?
What
can
go
horribly
wrong
that
I,
a
cluster
operator
may
need
to
know
simple.
It
works
almost
every
time.
A
If
there
are
branching
paths,
for
example,
with
configurations
where,
if
you're
one
kind
of
cluster
operator,
you
might
need
one
kind
of
configuration
versus
if
you're
another
kind
of
cluster
operator,
you
might
need
something
different.
What
you
need
to
do
is
provide
a
little
introductory
text
to
those
branching
paths
and
say
exactly
what
I
just
said.
If
you're
this
kind
of
person,
you
might
need
this.
If
you're
this
kind
of
person,
you
might
need
something
different,
simple,
a
couple
of
sneaky
plugs.
These
are
around
technical
writing
best
practices.
A
A
So
you
should
pick
that
up
if
you're
interested
in
learning
to
be
a
better
writer,
it
is
wonderful,
okay,
community
and
tooling,
when
you're
a
bit
more
of
a
medium-sized
project.
It's
time
to
start
thinking
about.
How
does
the
community
contribute
to
documentation?
Not
just?
How
does
the
project
do
documentation,
one
of
the
best
things
and
one
something
we
recommend?
Almost
every
project
in
the
cncf
do
at
some
stage
is
start
creating
documentation,
good
first
issues.
A
Documentation
is
rife
with
good
first
issues,
reorganize
a
page
or
rewrite
a
paragraph
or
correct.
The
grammar
in
this
paragraph
and
people
love
documentation,
good
first
issues,
engineers
and
writers
alike,
because
they
are
low
barriers
to
contribution
to
the
project.
It's
I
can
get
my
commit
in.
I
can
get
my
feet
wet.
I
can
learn
what
submitting
a
pr
to
this
project
is
without
breaking
the
code
base
and
that's
very
appealing
to
people.
So
I
think
if
you
can
always
keep
a
backlog
of
five
or
six
good,
first
issues,
you're
in
a
beautiful
state.
A
A
A
That
is
not
a
useful
amount
of
information,
especially
if
somebody
is
a
fairly
new
contributor
and,
as
we've
just
mentioned,
as
your
project
grows
and
as
your
community
grows,
you
have
more
new
contributors
and
they
will
go
to
the
docks
first,
looking
for
easy
kind
of
low
hanging
fruit,
so
if
there's
documentation
missing
in
your
dock,
set
really
take
the
time
to
scope
out
like
this
is
what
the
page
title
would
be.
Here
are
the
topics
that
we're
talking
about.
Who
would
be
good
people
in
the
project
to
contact
to
get
more
information
about
that?
A
There
are
natural
language
linters
available
the
biggest
one
is
called
veil
and
it
might
be
time
to
think
about.
Is
this
something
we
wouldn't
want
to
implement?
I
will
warn
you,
though,
in
every
professional
documentation,
environment
I've
ever
been
in.
We
have
used
veil
as
a
vs
code
plug-in,
but
never
as
failing
tests
on
the
actual
pr's,
because
it
just
tends
to
annoy
people
and
people
are
worse
at
grammar
than
they
think
and
that's
what
vale
will
try
and
fail
you
on.
Finally,
moving
docs
to
their
own
repo
is
something
we
recommend.
A
So,
if
you're
going
to
consider
moving
your
docks
to
their
own
repo,
do
it
why
they're
still
a
pretty
small
set
and
why
your
project
is
not
that
big
and
again,
if
you
choose
to
keep
them
in
the
code
repo,
I
warned
you
okay,
a
little
bit
of
a
note
specifically
for
cncf
projects,
and
I
sincerely
hope
there
are
non-cncf
maintainers
here.
A
key
component
for
cnc
cncf
graduation
is
attracting
external
users
and
new
contributors.
That
is
really
the
metric
that
they're
looking
for.
A
So
at
this
stage,
seeking
out
specialized,
helps
from
experienced
technical
writers,
works,
really
well.
Cncf
tech,
docs
office
hours
and
doc's
assessments,
as
we
talked
about
earlier
in
this
talk,
are
the
place
to
go
and
nate
waddington
is
one
of
the
people
you
encounter.
He
is
an
incredibly
friendly,
lovely
human
and
we
will
talk
a
little
bit
more
about
that
later.
Okay,
let's
talk
about
the
large
and
extra
large
projects,
so
this
really
corresponds
to
like
late
stage
incubating
projects
and
projects
that
are
graduated
in
the
cncf.
A
At
this
point,
documentation
sets
are
one
to
infinite.
To
give
you
a
picture,
I
think
the
kubernetes
project
has
about
400
pages
of
documentation
and
that's
in
one
language
and
bear
in
mind
that
the
kubernetes
documentation
is
localized
into
many
languages,
so
actually
there's
tens
of
thousands
of
markdown
pages
there.
A
It's
really
around
content
policies,
because
at
this
point
the
project
is
a
bit
of
a
magnet
for
marketing
and
the
documentation
is
a
wonderful
place
to
insert
marketing
people
love
doing
it.
There's
some
big
hard
problems
that
crop
up
like
localization
and
versioning,
and
we
need
to
start
thinking
about
advanced
automation
at
this
point
so
engineers,
like
rev
your
engines.
This
is
the
moment.
You've
been
waiting
for
here's
where
you
can
automate
the
docks
okay.
A
A
A
My
personal
advice,
particularly
for
graduated
projects,
is
you
need
to
seriously
consider
staffing
technical
writing
roles.
If
you
want
to
have
good
documentation,
it
will
not
get
done
without
full-time
help.
First
off
and
second
off,
when
you
look
at
a
documentation,
set
the
size
of
kubernetes.
That
is
not
actually
one
full-time
rule.
That's
five
to
ten
documentation
is
seriously
understaffed
and
open
source
and
it
will
start
to
cause
massive
sustainability
and
maintenance
problems.
A
The
next
thing
you
have
to
do
is
have
really
consistent
policies,
particularly
around
reviewing
and
merging
as
the
project
grows.
There
are
lots
of
people
who
think
they
understand
the
project,
and
you
need
to
get
really
really
clear
about
the
fact
that
documentation
is
the
truth
of
the
project
and
because
there
is
no
one
company
behind
it.
It
is
very
important
that
the
truth
remain
true,
which
means
that
as
random
kind
of
contributors
off
of
the
internet
go
like
wait
a
second,
I
know
a
kubernetes
thing.
Let
me
write
the
documentation.
A
You
need
to
know
who
can
verify
the
technical
truth
that
a
random
person
has
contributed,
because
that
contribution
is
very
likely
valuable,
but
it
is
also
potentially
very
harmful
if
untrue
content
policies,
what
happens
if
we
deprecate
a
feature,
question
mark?
How
do
we
communicate
that
to
people?
How
do
we
communicate
that
in
the
docs?
At
what
point
do
we
actually
remove
it
for
the
docs?
You
need
to
think
about
this
betas
and
alphas.
A
That's
a
cross-cutting
concern,
that's
something
that
both
the
technical
leads
and
the
project,
as
well
as
the
documentation
leads
need
to
understand,
because
it
creates
a
very
poor
documentation.
Experience
where
this
thing
looks
like
super
janky
and
shaky,
but
it's
not
up
to
documentation
to
decide
on
that
that
beta
and
alpha
policy
release
notes
as
your
project
grows.
People
start
actually
caring
about
what
you've
done
and
you
need
to
actually
explicitly
say
in
version
xyz
changes.
Why
is
it
abc
came
into
place
depending
on
the
project?
A
This
is
super
important
because
one
people
are
building
production
systems
on
you
at
this
point.
You
need
to
tell
them
if
there
are
any
limitations.
Those
are
very
important
to
them.
Two,
when
you
get
to
a
place
where
you
have
multiple
contributors,
particularly
multiple
corporate
contributors,
you
need
to
understand
what
is
out
of
scope,
or
else
people
will
like
submit
whatever
they
want,
as
dawn
said
and
there's
a
whole
bunch,
more
content,
policies
that
you
can
put
into
place,
but
you
need
to
start
thinking
about
it
at
this
stage.
A
Automations
merging
approvals
and
reviewer
assignments
documentation,
particularly
if
you
have
technical
writers
on
staff,
requires
a
very
different
kind
of
review
that
most
projects
are
both
are
used
to.
The
other
thing
with
documentation.
Review
as
well
is
that
it
is
something
that
people
feel
that
they
all
have
an
opinion
on,
because
it's
just
english
language
right.
I
know
how
to
write.
I
know
how
to
talk
managing
managing
reviews
so
that
they
don't
become
pedantic
is
a
super
important
skill
to
start
thinking
about.
A
A
So
what
we're
talking
here
is
really
like
pulling
like
all
the
cli
flags
out
of
a
code
file
and
then
pulling
whatever
help
is
coming
up
on
that
command
line
interface
and
like
dumping
it
into
a
table
and
then
dumping
it
into
your
documentation
when
you're
a
large
project.
This
makes
a
lot
of
sense
when
you're
a
small
project.
I
would
encourage
you
not
to
do
this
other
hard
problems.
A
Localization
and
community
policies
around
this
localization
is
interesting
because
it
impacts
something
else
on
this
list,
which
is
performance
because
localization
increases
the
amount
of
files
that
you
have
in
your
documentation,
repo
exponentially
every
time.
Somebody
gets
a
shiny,
little
thought
in
their
head
of
localizing
it
into
their
favorite
language.
A
Containerization
starts
to
make
a
lot
of
sense
for
large
project
projects
because,
for
example,
the
kubernetes
project
tends
to
have
about
150
prs
in
documentation
open
at
any
given
time,
and
a
lot
of
them
fail,
not
necessarily
because
the
content
is
bad,
like
it's
markdown
content,
it's
not
that
dramatic
y'all,
but
because
the
build
environments
that
people
are
using
locally,
don't
match
the
build
environments
that
the
server
is
using.
This
is
the
perfect
case
for
containerization
versioning
docs
is
another
one.
A
A
These
are
np
hard,
because
no
individual
product
can
solve
them.
They
are
a
an
artifact
of
open
source
as
it
is
today.
I
find
these
fascinating
and
that's
why
I'd
like
to
bring
your
attention
to
them.
The
two
that
come
to
mind.
How
do
I
get
actual
technical
writers
contributing
slash?
My
engineers
want
to
write
less.
How
do
I
make
that
happen?
A
A
My
engineers
want
to
write
less.
What
do
I
do?
Technical
writer
absence
in
open
source
is
a
result
of
misaligned
understanding
on
the
part
of
the
organizations
that
are
doing
this
open
source
is
critical
infrastructure
and
it
must
be
staffed
in
the
same
way
that
you
would
staff
literally
any
other
project
or
product
right
now.
A
A
You
need
to
staff
the
people
who
are
going
to
write
things
down
onto
the
project.
You
need
to
staff
the
qa
staff
onto
the
project.
You
need
to
staff
the
release
engineers
onto
the
project.
It
simply
will
not
happen.
Otherwise.
The
way
I
sort
of
think
about
this
is
that
open
source
in
many
ways
is
the
closest
that
software
gets
to
the
sort
of
same
standardization
that
other
engineering
practices
have
where
it's
like.
You
would
never.
A
A
So
the
answer
to
this
question,
in
my
opinion,
is
to
be
more
responsible
and
to
have
a
bit
of
an
attitude
shift
within
open
source,
okay
content
organization
and
relatively
mature
projects.
I
don't
have
an
answer
to
this
one,
but
I
can
tell
you
that
this
is
a
problem
that
the
kubernetes
project
faces,
and
I
think
the
issue
is
around
the
fact
that
horizontal
project
concerns
so
release.
Engineering
is
one
of
them.
A
A
So
I
think
if
we
can
answer
that
question,
we
can
unblock
the
actual
work
quickly.
Docs
assessments,
office
hours
go,
do
them
if
you're
a
cncf
project,
there's
some
more
content
for
you
to
consume.
If
you
want
to
learn
how
to
actually
write
great
documentation,
some
other
resources,
if
you
need
some
technical
writers-
and
you
want
to
talk
to
some
people-
the
write
the
docs
community
is
where
they
all
hang
out.
There
is
both
conferences
and
the
slack
the
slack
does
in
fact
have
an
open
source
channel
pop
in
there.
A
Google
season
of
docs
is
a
program
that
pairs
wannabe
technical
writers
with
open
source
projects
for
a
paid
internship.
There
are
more
cncf
resources
available.
If
you
look
at
the
service
desk,
there
is
in
fact
a
massive
list
of
the
things
the
documentation
team
can
do
for
you.
The
other
thing
you
can
do
through
the
cncf
is
participate
in
lfx
mentorship,
where
a
where
you
mentor
somebody
into
the
project
for
documentation
or
other
reasons.
A
Finally,
I
guess
as
a
resource
I
go
by
my
name
on
twitter,
celeste
horgan
and
I
very
often
tweet
about
docs.
This
talk
if
you
enjoyed
it,
was
the
result
of
one
of
those
tweet
threads
and
I
have
other
talks.
Maybe
planned
based
on
other
tweet
threads.
So
if
this
is
content,
you're
interested
in
consuming
follow
me
on
twitter
and
we
have
a
little
bit
of
time
for
questions.
B
A
So
just
the
question
for
those
of
you
who
didn't
hear:
how
do
you
balance
high
quality,
docs
versus
docs,
that
you
don't
have
content
for?
There
is
no
balance,
always
go
for
completion
completion.
Is
the
base
state
documentation
at
its
best
documents,
the
truth
of
a
system
and
if
it
is
not
documenting
the
full
truth
of
a
system,
it's
not
doing
its
job,
it
can
do
its
job
with
bad
grammar.
It
can
do
its
job
with
bad
structure.
A
A
Okay,
so
the
question
for
those
who
didn't
there
isn't
back
to
mike
by
the
way,
guys
the
question
for
those
who
didn't
hear
it
is:
can
you
expand
on
why
you
would
want
to
move
your
docs
out
of
the
code
repository
how
that
affects
ownership
of
the
documentation
and
just
expand
on
it
a
little
bit
nate
and
I
are
just
like
making
eye
contact,
because
this
is
like
this
is
the
struggle
of
every
project
and
every
project
is
like.
Do
I
have
channel?
A
I
really
recommend
a
yes.
The
problem
with
keeping
your
docs
in
the
code
repository
is
at
some
point.
They
then
become
a
dependency.
They
become
dependent
on
your
code
tests
passing,
which
seems
trivial,
especially
when
you're
a
small
project
you're
like
why?
Wouldn't
my
tests
pass
all
the
time,
whereas
anybody
who
has
worked
on
any
sufficiently
large
and
mature
code
base
knows
that
tests
get
flaky
and
then
they
stay
flaky
and
then
that's
just
what
it
is
and-
and
you
know
every
large
code
base
I've
ever
worked
on-
has
had
a
flaky
test
situation.
A
So
that's
thing
number
one.
You
get
into
a
situation
where,
like
really
simple,
markdown
changes
get
held
up
because
the
integration
tests
aren't
passing
and
the
person
doing
the
documentation,
maybe
doesn't
have
the
knowledge
to
unblock
that
implementation
that
flaky
test.
So
as
a
result,
people
stop
contributing
to
documentation
because
they
look
at
this.
They
go
like.
I
don't
know
why
this
test
is
broken.
I
don't
want
to
solve
this.
I
don't
know
anything
about
this
part
of
the
code
base.
A
A
Hot,
take
almost
no
open
source
project.
I've
seen
has
actually
done.
Those
deeper
integrations
that
take
advantage
of
being
in
the
code
base.
The
only
one
I've
seen
is
maybe
kubernetes,
and
that
is
frankly
arguable
that
is
also
accomplishable.
By
pulling
in
like
specific
commits
from
a
different
code
base
like
git
can
do
that,
for
you
it's
a
little
complicated,
but
it
works.
A
I
think
it
just
makes
it
easier
if
it's
in
its
own
repository,
because
then
the
people
who
can
maintain
at
that
repository
level
like
they
don't
necessarily
need
to
know
everything
about
the
code
base.
They
don't
need
to
know
how
all
that
works
like
it
just
makes
life
easier.
So
sorry,
if
that
was
a
little
long-winded,
I
think
I'm
being
like
summarily
kicked
off.