►
Description
This is the annual retrospective and planning meeting for SIG Docs. We'll review docs accomplishments in 2018, set high-level priorities for the coming year, and set specific goals for content in the first quarter of 2019.
A
B
So
this
led
to
like
a
phase
rise
charge.
A
question
like:
why
is
crew
Benetti
so
difficult
for
people
to
understand,
right
and
went
down
this
rabbit
hole
and
then
Dominic
showed
me
kind
of
like
systems
modeling.
He
specifically
fundamental
modeling
concepts
which
we'll
talk
about
a
little
later
too,
but
like
how
he's
used
this
in
other
projects?
To
really
help
improve
people's
mental
models
and
communicate
and
so
I
realized,
we
could
really
apply
this
to
the
criminais
documentation.
B
C
One
is:
writing
is
Nature's
Way
to
let
you
know
how
sloppy
your
thinking
is,
and
the
addition
to
that
is
mathematics
is
nature's
way
to
let
you
know
how
sloppy
your
writing
is,
and
that
is
freely
adopted
so
that
the
second
quote
reads:
systems.
Modeling
is
nature's
way
to
let
you
know
how
sloppy
your
writing
actually
is.
So
when
we
come
to
the
question,
what
is
a
model
right?
A
model
is
an
abstraction
of
a
system.
C
A
model
is
an
abstraction
of
a
system
so
that
each
and
every
fact
about
the
model
is
a
fact
about
the
system.
The
opposite
does
not
necessarily
hold
true.
I
can
derive
more
facts
from
the
system,
then
I
can
from
the
model.
In
this
case,
for
example,
looking
at
the
system,
I
could
see
its
physical
dimensions.
I
could
measure
its
operating
temperature
boundaries.
This
is
something
that
the
model
does
not
reflect.
However,
let
me
state
this
again.
Each
and
every
fact
about
the
model
is
also
affect
about
the
system.
Now.
C
C
This
actually
leads
nicely
to,
or
this
actually
enables
us
to
clearly
define
the
roles
of
novice
intermediate
and
expert.
So
it
shows
that
every
fact
that
the
novice
knows
is
a
fact
that
the
intermediary
knows
and
is
the
fact
that
the
expert
knows
intermediates
no
more
than
novices
so
and
they're
experts
no
more
than
the
novice
and
the
intermediary.
However,
there
is
a
very
important
point
to
make,
and
that
is
that
no
fact
that
the
intermediary
knows
contradicts
or
invalidates
effect
that
the
novice
knows-
and
the
same
is
true
for
the
experts.
C
No
effect,
the
expert
knows
contradicts
the
fact
that
the
intermediary
nose
or
the
novice
nose.
This
sounds
fairly
straightforward
and
reasonable.
Yet
I
can
point
to
a
multitude
of
places
in
the
documentation
of
kubernetes,
where
this
is
not
true,
where
documentation
for
or
documentation
targeted
for
the
intermediate
or
the
expert
actually
invalidates
statements
that
were
made
before
so
now.
The
question
after
knowing
what
a
model
is,
why
do
be
actually
model
right,
and
this
presentation
focuses
on
one
reason
and
one
reason
only.
C
So,
to
establish
a
baseline,
we
assume
that
if
two
people
study
the
same
system,
they
will
arrive
at
the
same
mint
model
and
let
us
further
assume
that,
for
example,
for
kubernetes
it
takes
me
three
months
or
four
hundred
eighty
percent
hours
to
actually
sufficiently
understand
the
system
to
transfer
people
between
I'm,
sorry
to
transfer
knowledge
between
people,
the
sender,
studies
the
system
and
creates
a
model
for
the
recipient.
The
recipient
then
studies
the
model
instead
of
the
system.
C
For
the
sake
of
the
argument,
let
us
assume
that
it
takes
me
another
three
months
to
actually
create
sufficiently
accurate
model
of
kubernetes,
but
now
it
takes
recipient
of
them,
or
only
one
month,
160
person
hours
to
study
the
model.
Now
there
are
only
two
participants
in
that
all
right,
we're
in
the
negative.
C
We
actually
lost
one
month
here,
but
if
we
apply
this
to
cube
con-
and
we
assume
there
are
4,000
participants
in
cube
con,
the
accurate,
accurate
modeling
would
actually
save
615
person
years
for
4,000
cube
con
visitors
to
accurately
understand
cube
corn
queue
Benares.
So
this
actually
shows
how
much
multiplying
force
is
in
good
documentation
and
is
in
good
modeling
and
of
course
nothing
ever
comes
easy
right.
So
there
are
some
challenges
and
the
main
challenge
when
it
comes
to
modeling
in
the
context
of
communication,
is
about
encoding
loss
and
decoding
loss.
C
Now
there
are
a
few
examples
for
for-4
challenges
and
problems,
one
for
example,
misleading
models
in
kubernetes.
A
great
example
for
a
misleading
model
is
the
notion
of
a
declarative
system
and
the
desired
state,
so
previously
I
introduced
that
each
facts
about
a
model
needs
to
be
a
fact
about
the
system.
This
is
a
definition
of
a
systems
model.
However,
more
than
once
do
we
have
situations
where
not
each
fact
about
the
model
is
a
fact
about
the
system.
C
There
is
a
certain
overlap,
but
you
already
have
to
know
you
have
to
be
an
expert
to
know
how
far
you
can
take
this
analogy.
A
very
good
example
here
is,
for
example,
a
train
and
a
toy
train
I
can
derive,
for
example,
the
physical
appearance
and
the
physical
dimensions
from
the
toy
train
of
the
actual
train.
If
I
want
to
take
this
any
further,
I
cannot
write
inspecting
the
toy
train.
I
see
that
the
toy
train
runs
on
little
rubber
wheels
is
the
actual
train
running
on
rubber
wheels.
C
Of
course
it
is
not,
and
we
all
know
that,
but
that
is
because
we
already
know
about
trains,
so
these
kind
of
models
only
work
for
you.
If
you
already
know
enough
about
kubernetes
so
that
you
know
you
do
not
take
it
too
far,
because
the
analogy
breaks
down
in
other
places
when
we
come
to
the
declarative,
state
or
kubernetes
as
a
declarative
system
working
towards
a
desired
state.
C
The
by-the-book
definition
is
that
you
start
from
a
current
state
and
the
system
will
derive
a
set
of
coordinated,
calculated
actions
that
take
you
from
the
current
state
to
the
desired
state.
However,
this
is
not
how
kubernetes
actually
operates.
Kubernetes
operates,
one
step
of
a
time.
It
is
a
control
system
that,
at
each
point,
in
its
in
its
state
graph,
determines
the
next
action
it's
gonna
take
until
there
are
no
or
actions
to
take
and
kubernetes
reached
a
steady
state.
C
Now,
at
a
first
glance,
there
is
a
considerable
overlap
between
our
definition
of
declaratives
system
and
the
definition
of
control
system.
However,
if
you
take
this
too
far,
your
mental
model
cannot
explain
right
why
you
see
certain
behavior
in
kubernetes,
for
example,
if
it
comes
to
the
replica
set
and
already
pre-existing
labels,
other
problems
are,
for
example,
misleading,
terminologies
or
inaccurate
terminology.
A
great
example
in
the
context
of
kubernetes
is
the
term
api
server.
So
in
the
kubernetes
documentation,
the
active
part
is
called
the
API
server.
C
The
passive
part
is
called
the
API
server
and
the
totality
of
these
parts
is
called
the
API
server,
which
does
not
make
it
very
like
easy
or
straightforward
to
talk
about
the
individual
parts.
So
one
thing
we
did
is
a
v4.
Our
blog
posts
adopted
a
different
terminology.
Talking
about
the
active
parts
of
kubernetes.
As
the
kubernetes
api,
the
passive
parts
of
kubernetes
as
the
kubernetes
objects
tour
and
then
the
totality
still
as
API
server.
C
That
also
enables
a
clear
refinement,
because
especially
the
novice
from
sometimes
also
bordering
to
the
intermediary,
asked
how
etcd
actually
fits
into
that.
If
you
want
to
refine
this
model
and
then
refined
this
terminology,
is
this
actually
fairly
straightforward
to
explain
how
the
etcd
fits
into
the
into
the
API
server?
C
Now,
with
everything
we
do
with
the
approach
that
we
are
trying
to
apply,
we
try
to
minimize
encoding
loss
and
decoding
loss
and
therefore
increase
efficiency
of
the
knowledge
transfer
between
the
sender
and
the
receiver.
So
in
summary,
we
basically
aim
for
mental
models
that
enable
the
reader
to
reason
about
kubernetes.
C
We
aim
for
mental
models
that
prevent
the
reader
from
drawing
the
wrong
conclusions
about
kubernetes
by
not
knowing
how
far
to
take
oh
gee
and
in
general,
we
aim
for
a
sound
path
from
novice
to
intermediate
to
expert
by
adding
one
fact
after
the
other,
without
ever
contradicting
a
previously
made
statement,
and
with
that
I
hand
back
to
Andrew.
Thank
you.
B
Thanks
Dominic,
so
let
me
talk
a
little
bit
about
our
process
because,
let's
see,
let's
see
so,
we've
been
writing
blog
posts
and
this
is
sort
of
like
a
quick
and
dirty.
You
know
MVP
of
like
creating
these
different
mouths.
So
we've
been
trying
different
topics,
you
know
a
high
availability
or
you
know,
pods
communities
API
serve
and
that
sort
of
thing
right
and
to
do
that,
we've
had
to
we've.
B
We've
been
doing
presentations
to
like
sort
of
test
out
in
sig
Docs
and
we've
also
been
doing
interviews
with
engineers
to
help
validate
our
models.
So
the
idea
is
to
like
kind
of
build
up
a
bunch
of
source
material
in
the
blog
posts
and
get
feedback
and
make
sure
like
people
understand
it
and,
like
things
are
accurate
and
once
that
is
done,
the
plan
is
to
then
fold
that
back
into
the
kubernetes
I/o
documentation,
because
we
still
need
to
decide
exactly
like
to
what
level
you
know
we.
B
You
know
we
want
to
integrate
like
these
diagrams
and
stuff
because
that's
been
pointed
out
before,
like
some
of
them
are
more
technical
and
you
need
to
know
about
sort
of
like
the
language
of
of
modeling,
but
others
are
more
straightforward
and
you
can
just
you
know,
read
it
without
knowing
anything
about
FMC
and
still
understand
it.
So
you
know
that's
what
we're
gonna
need
to
do
is
kind
of
make
these
decisions
of
like
what
we
need
to
add
to
the
documentation
and
what
needs
to
be
more
clear
and
I.
B
B
No
because
we've
kind
of
been
doing
this
as
a
discovery
thing.
Oh,
so
the
question
was:
do
we
have
a
list
of
models
that
were
going
through,
so
we?
This
is
more
of
sort
of
like
a
organic
discovery.
So
we
you
know,
as
people
like
bring
up
topics
and
stuff
we've
been
mulling.
It
and
that's
kind
of
helped
us
to
start
figuring
out
like
what
are
the
important
topics
and
what
concepts
are
kind
of
still
need
to
be
filled
out.
B
So
I
think
pretty
soon
we'll
be
able
to
have
a
more
complete
list
and
then,
then,
from
that,
we
can
build
like
a
dock
plan
in
terms
of
like
what
needs
to
be
changed
in
the
conceptual
section
and
grazed
Ohio
right
so
yeah.
So
there's
a
proof
of
concept
and
also
just
mapping
out
the
space,
like
really
understanding
like
what
concepts
are
important
to
two
novice
users.
B
C
B
B
C
All
right
so
for
the
scheduler,
this
diagram
depicts
the
high-level
architecture
of
kubernetes.
So
in
this
case,
please
note
that
the
individual
components
like
controllers
scheduler
cubelet
they
do
not
communicate
directly,
but
they
communicate
indirectly
via
the
kubernetes
api
and
the
kubernetes
object
store.
So
already
from
this
high-level
view,
you
can
derive
the
guiding
principle
that
kubernetes
in
the
individual
components
of
kubernetes,
do
not
share
state
by
communicating
they
communicate
by
sharing
state.
Now
when
it
comes
to
the
scheduler,
obviously
the
scheduler
is
tasked
with
pods
pods
and
nodes.
So
on.
C
The
first
question
is:
what
is
the
typical
sequence
of
events
that
we
see
in
the
context
of
the
scheduler
and
that
is
actually
fairly
simple
to
express
after
a
user
or
a
controller
creates
a
part.
The
scheduler
monitoring
the
object
store
for
unassigned
pods
will
assign
this
part
to
a
node.
Subsequently,
the
cubelet
monitoring
the
object
store
for
assign
pods
will
execute
this
part.
So
in
summary,
mission
statements
reads:
the
kubernetes
scheduler
assigns
a
pod
to
some
node
in
all
right,
but
then
the
question
arises:
what
does
assigning
actually
mean
right
and
diving
deeper?
C
The
answer
is
also
fairly
straightforward,
so
this
diagram
depicts
the
kubernetes
objects
that
are
of
interest
to
the
kubernetes.
Scheduler
kubernetes
represents
a
part
as
a
kubernetes
pod
object,
a
node
as
a
kubernetes
node
object
and
the
assignment
of
a
pod
to
a
node
as
a
kubernetes
binding
object.
So
we
can
define
equipped
with
this
knowledge
that
a
pod
is
bound
to
a
node
in
we
are
the
binding,
be
if,
and
only
if
you
can
read
the
formula,
the
bindings
name,
equal
supports
name.
C
The
bindings
namespace
equals
the
pods
namespace
and
the
bindings
targets
name
equals
the
nodes
name.
So
equipped
with
this
knowledge,
we
may
now
formally
define
the
or
formally
describe
the
task
of
the
scheduler
s.
The
kubernetes
scheduler
for
a
pod
P
selects
a
node
n
and
creates
a
binding
B
so
that
the
binding
predicate
we
just
talked
about
bound
to
part
two
node
via
the
binding
B
yields.
True
so
I
got
a
pod
object,
I
got
a
node
object
and
if
there
is
a
binding
object
that.
C
C
No
further
questions
asked
if
this
node,
if
this
node
name
is
not
set,
the
kubernetes
scheduler
will
select
a
node
and
if
it
finds
a
suitable
node,
it
will
then
create
a
binding
object
between
the
pod.
And
this,
not
so
graphically
represented,
fairly
straightforward,
node
name
is
empty,
is
not
empty
uses.
Node
node
name
is
empty,
select
a
node.
C
Now,
selecting
a
node
for
the
for
a
pod
is
a
two-step
process.
First,
the
scheduler
selects
a
subset
of
nodes
that
are
qualified
to
host
the
pod
and
then
second,
the
scheduler
selects
a
node
from
this
sub
set
that
has
a
highest
ranking
or
the
highest
priority
for
this
pot.
How
does
this
look
like?
Well,
we
have
a
set
of
filter
functions
to
actually
select
the
qualified
nodes,
so
you
can
think
of
the
filter
function
as
a
conjunction
of
a
set
of
filter
functions
that
are
implemented
in
the
scheduler.
C
One
example
for
a
filter
function
is
a
basic
sanity
check.
All
right.
Does
the
node
pass
basic
checks?
In
that
case,
we
look
at
the
attributes
of
the
node
object
like,
for
example,
the
unschedulable
flag,
better,
be
not
set.
The
node
phase
shall
be
running
and
there
should
be
a
node
condition.
The
node
condition
ready
equals.
True.
Only
then
will
this
node
be
considered
eligible
to
run
this
pod.
Once
again,
the
formula
is
actually
straightforward
on
this
filter.
The
implementation
details
of
this
aura
no
question
asked
the
implementation.
C
Details
are
fairly
complex
on
a
specification
level.
This
is
it
alright.
There
is
no
much
more
to
it
to
the
to
the
basic
sanity
check.
Now
we
got
other
checks
like,
for
example,
taints
and
toleration
who
doesn't
like
tension,
toleration
'z
once
it
comes
to
notes
and
pots.
Surprisingly,
actually
taints
in
toleration,
czar
fairly
straightforward.
The
object
model
behind
it
is
not
even
that
complex
and
the
statement
is
also
a
fairly
simple
one.
C
The
scheduler
may
assign
a
part
P
to
a
node,
and
if
and
only
if,
for
each
taint,
that
is
an
element
of
the
nodes
taints
there
must
be
a
toleration
that
is
an
element
of
the
pods
toleration
x'
so
that
the
Toleration
matches
it
ain't
done.
This
is
the
entire
specification
of
tents
and
toleration.
X'
again,
the
implementation
in
the
scheduler
in
source
code
may
be
fair.
Is
actually
fairly
complex
right,
but
the
specification
on
a
specification
level.
This
is
it
if
we
come
to
affinity
or
anti
affinity.
C
I
personally
was
surprised
that
the
object
model
behind
that
is
way
more
complex
than
behind
tints
and
toleration.
X',
and
so
are
the
formulas.
So
I
only
go
over
them
on
the
highest
level.
The
scheduler
may
assign
a
part
P
to
a
node
n.
If
and
only
if,
the
not
affinity,
pot,
affinity
and
pot
anti
affinity
all
hold
true
for
the
node
affinity.
For
example,
a
port
must
be
assigned
to
a
node,
so
so
such
that
the
nodes
label
matches
the
pods
node
affinity
requirements.
The
same
can
be
said
about
the
port
affinity.
C
The
same
can
be
said
about
the
power
anti
affinity.
I
spare
you
that
and
we
go
straight
to
the
rating
functions.
Rating
functions
are
just
the
same.
We
run
the
part
and
the
node
through
rating
functions.
We
sum
them
up
right
and
we
select
a
node
from
the
highest
rated
once
I
would
say
it's
enough
graphs,
it's
enough
math,
I'm,
pretty
sure
you
all
get
the
gist.
They
basically
look
like
the
filter
functions
and
we
hold
on
I
lost
my
preview
yeah.
C
Here
we
go,
they
look
like
the
filter
functions
and
we
go
right
into
a
very
quick
case
study
for
for
the
scheduler,
so
we
have
a
cluster
and
in
this
cluster
we
have
a
few
nodes
without
a
GPU
and
we
have
some
nodes
with
a
GPU.
We
have
some
parts
that
require
the
GPU
and
may
have
some
parts
that
do
not
require
the
GPU.
C
So
what
we
going
to
do
first
first,
in
this
case
many
possibilities,
but
this
is
the
way
that
we
are
going
down
to
now.
We
add
a
tint
to
the
notes
and
with
this
tent
immediately,
none
of
the
pods
is
eligible
to
run
on
this
node
right.
That's
why?
For
the
parts
that
require
the
GPU,
we
need
to
give
them
a
toleration
so
that
they
tolerate
this
tint.
However,
now
that
only
states
that
the
pods
can
run
on
this
node,
but
it
doesn't
say
that
the
pods
must
run
on
this
node.
C
For
this,
we
need
to
get
a
step
further
and
we
add
some
labels
to
the
nodes
which
will
not
change
the
possible
assignments
at
this
moment.
But
then
we
give
the
nodes
I'm.
Sorry,
we
give
the
ports
a
node
affinity
and
then,
with
the
node
affinity,
we
actually
split
the
set
of
nodes
and
the
set
of
ports,
just
according
to
our
specifications,
where
the
pods
not
requiring
GPU
run
only
on
pods
on
notes,
without
the
GPU
and
the
pods
requiring
GPU
only
run
on
notes
with
the
GPU
and
I
do
believe.
D
C
C
On
the
very
first
slide
right,
maybe
look
at
the
control
loop
at
the
highest
level.
Right,
this
and
I
said
it
defines
the
control
loop
in
its
totality
right.
If
we
now
want
to
go
a
step
deeper,
we
need
to
look
into
select,
but
you
are
right.
That
is
not
just
a
refinement.
There
are
also
aspect
models
right
where
I
say
all
right
now
you
understand
what
the
part
is.
You
underst,
you
understand
what
the
schedule
is.
You
know
what
chains
scintillations
are
about.
C
North
affinity,
anti
affinity
is,
but
now
let
me
tell
you
also
about
the
possibility
of
the
controller
to
evict
nodes,
so
there
I'm
sorry
to
evict
pots.
So
then
you
would
actually
add
right.
Other
commands
that
the
scheduler
can
issue
right
now.
We
model
the
scheduler
so
that
it
can
only
issue
one
command
that
is
create
all
it
does
in
this
model.
Is
it
creates
a
binding
right
once
you
come
in
and
now
let
me
tell
you
more
about
the
scheduler
right.
C
Then
you
enhance
the
command
surface
of
the
scheduler
and
say,
and
now
this
is
where
the
scheduler
can
actually
start
to
evict
pods
right.
So
you
add
facts
to
the
model.
You
can
do
that
horizontally.
You
can
do
that
vertically
right,
but
the
most
important
one
is.
You
never
contradict
the
previously
made
statement
when
you
just
add
more
detail
right
and
me
as
a
novice.
B
B
C
And
let
me
state
one
more
thing
why
I
said
this
is
one
of
my
favorites
right,
the
kubernetes
scheduler,
the
implementation
of
it
is
very
complex.
It
has
like
many
many
thousand
lines
of
source
code
right,
but
it
is
sufficiently
described
with
a
12
line
specification
right
that,
basically
on
in
all
areas
of
your
kubernetes
journey,
whether
you're,
a
beginner
nobis
or
an
expert
that
you
can
understand,
and
that
will
help
you
to
build
an
actual
sufficient
mental
model
and
lift
the
lift
the
curtain
of
magic
right
behind
a
single
component.