2. Questions at the end…
…but
you
can
always
ask
me
anything:
2
documenting 20 cloud services
across 130 GitHub repositories
With 800 docs contributors in 4 years
@annegentle, #writethedocs
anne.gentle@rackspace.com
www.justwriteclick.com
3. Git and GitHub
▪ 2005
born
after
spectacular
Linux
tooling
failure
▪ Social
web,
leads
to
social
coding
▪ Git
is
for
command
line,
GitHub
is
the
web
interface
▪ Cross-‐platform
tooling
-‐
Windows,
Mac,
Linux
▪ Merge
files
rather
than
a
“lock
and
checkout”
model
▪ Non-‐linear
branching
model
3
4. GitHub Vocabulary
4
BRANCH
Indicator
of
divergence
from
base
COMMIT
Point
in
time
snapshot
of
repository
with
changes
FORK
Copy
repository,
copy
of
repository
PUSH
Move
changes
branch
to
branch
ORGANIZATION
Collection
of
repositories
PULL
REQUEST
Comparison
of
edits
to
see
if
team
wants
to
accept
changes
RESPOSITORY
Collection
of
stored
code
or
documentation
ISSUE
Defects,
tasks,
or
feature
requests
6. Collaborate Where Users Are
▪ Curate
the
audience
▪ Write
with
and
for
the
audience
▪ Reward
the
audience
6
7. 7
Motivations
Ensure
that
contributors
are
valued
and
rewarded!
▪ Sense
of
belonging
▪ Pay
it
forward
(reciprocity)
▪ Effective,
time-‐saving,
user
support
▪ Reputation,
recruiting
Flickr:elkaypics
8. MOTIVATIONS
8
Ensure
that
contributors
are
valued
and
rewarded!
▪ Sense
of
belonging
▪ Pay
it
forward
(reciprocity)
▪ Effective,
time-‐saving,
user
support
▪ Reputation,
recruiting
LET’S
CURATE
Authors
Processes
Tools
Mindsets
Attitudes
Jobs
Flickr:roswellsgirl
9. MOTIVATIONS
9
Ensure
that
contributors
are
valued
and
rewarded!
▪ Sense
of
belonging
▪ Pay
it
forward
(reciprocity)
▪ Effective,
time-‐saving,
user
support
▪ Reputation,
recruiting
TREAT
DOCS
LIKE
CODE
Flickr:roswellsgirl
10. Long Tail Contributions
▪ Rise
of
the
niche
▪ Finding
like-‐minded
people
interested
in
your
content
▪ Dark
corners
of
knowledge
gap
are
filled
with
docs
10
11. The Docs Suck
▪ In
what
way?
▪ Which
page?
▪ How
can
I
get
it
not
to
suck?
11
12. Doc Issues Tracking
▪ Tasks,
outright
errors
and
feature
requests
▪ I’ll
triage
the
issue
and
guide
you
in
fixing
it,
issue
reporter
▪ http://guides.github.com/
features/issues/
12
13. Writers Never Get Reviews
Documentation
system
so
separate
from
code
system
that
technical
reviews
are
through
email
Or
*gasp*
Frozen-‐in-‐time
PDF
files
13
Flickr:elkaypics
14. Reviewers Fix Docs
“This
is
wrong,
here’s
how
to
fix
it”
▪ Working
in
the
same
collaboration
tools
as
technical
people
gives
better
reviews
▪ We
can
merge
as
many
as
50
patches
per
day;
running
four
automated
tests
per
patch
and
requiring
two
humans
to
check
the
patch
and
click
in
order
to
publish
14
17. White Coat Tools
Closely
guarded
secrets
of
proprietary
tool
chains
with
expensive
per-‐seat
licenses
Or
Secret
developer
workflows
are
mysterious
to
writers
17
Flickr:darthnick
18. Beautiful Docs
▪ Widely
accepted
tooling
built
in
the
open
so
we
can
make
it
work
for
us
and
for
devs
(readthedocs.org)
▪ Simple
markup
▪ Flat
file
builds
▪ We
can
patch
and
log
issues
against
the
tooling
18
19. 19
ONLY
DEV
TEAMS
GET
CI/CD
Deploying
containers
and
micro
services
oh
my.
Docs,
use
some
horrifyingly
slow
proprietary
tool,
kthnxbai.
Flickr:photohome_uk
20. 20
CI/CD
FOR
ALL
▪ Docs
can
be
published
automatically
after
reviewers
merge
the
change
▪ Docs
can
have
simple
tests
to
ensure
quality
and
that
you
“don’t
break
the
build.”
▪ Scrape
the
code
to
build
more
helpful
docs
(especially
reference)
▪ https://opensource.com/business/15/7/
continuous-integration-and-continuous-
delivery-documentation
Flickr:pedrovenzini
21. What Pairs Well with GitHub?
▪ Simple
markup:
Markdown,
RST
▪ GitHub
Pages:
http://pages.github.com
▪ Static
site
generators:
https://
staticsitegenerators.net/
▪ Well-‐documented
style
guide
and
contributor
guide
▪ Open
licensing:
Creative
Commons
▪ Borrowing
development
techniques
21
22. ========================================
Discover the version number for a client
========================================
Run the following command to discover the version number for a client:
.. code-block:: console
$ PROJECT --version
For example, to see the version number for the ``nova`` client, run the
following command:
.. code-block:: console
$ nova --version
2.31.0
Source | Output
22
23. Who Uses Git and GitHub?
▪ O’Reilly
Media
for
book
publishing
▪ GitHub
uses
GitHub
to
document
GitHub
▪ OpenStack
uses
open
source
Git
▪ Rackspace
Cloud
documentation
uses
GitHub
▪ Many,
many
more
organizations
23
25. Flickr:pedrovenzini
What Are Some
Difficulties?
▪ Scope
and
scale
questions
▪ Official-‐ness
▪ Identity
▪ Naming
25
Flickr:davebloggs007
QUALITY
GATE
You
shall
not
pass…
▪ Test
for
unwanted
white
space
▪ Test
docs
syntax
▪ Test
docs
build
26. Flickr:pedrovenzini
What Are Some
Difficulties?
▪ Scope
and
scale
questions
▪ Official-‐ness
▪ Identity
▪ Naming
26
Flickr:hddod
END
THE
TEDIUM
ENABLE
THE
ROBOTS
▪ Build
the
docs
and
publish
them
to
drafts
or
staging
area
▪ Docs
are
always
available
for
reviews
27. Flickr:pedrovenzini
Coach Better Writing
▪ Become
the
experts
and
consultations
while
enabling
others
to
improve
their
writing
▪ The
people
with
the
knowledge
can
become
better
writers
and
learn
more
empathy
by
writing
for
the
users
27
Flickr:philgaldys
28. Flickr:pedrovenzini
What Are Some
Difficulties?
▪ Scope
and
scale
questions
▪ Official-‐ness
▪ Identity
▪ Naming
28
Flickr:mortimer
CREATE
TEAMS
▪ We
now
divide
the
work
by
deliverable:
user
guides,
install
guides,
configuration
guides
▪ We
scrape
the
code
as
often
as
we
can
to
deliver
continuously
29. Flickr:pedrovenzini
What Are Some
Difficulties?
▪ Scope
and
scale
questions
▪ Official-‐ness
▪ Identity
▪ Naming
29
Flickr:turbojoe
BUILD
A
REPUTATION
▪ Measure
quality
and
quantity
▪ Count
contributions
and
improvements
▪ Compare
over
time;
benchmark
and
reward
30. “We’re
crazy,
but
we’re
writing
a
book
in
five
days.”
Anne
Gentle
https://youtube.com/watch?v-‐
IYfHEy6E2n0
30
32. MOTIVATIONS
32
Ensure
that
contributors
are
valued
and
rewarded!
▪ Sense
of
belonging
▪ Pay
it
forward
(reciprocity)
▪ Effective,
time-‐saving,
user
support
▪ Reputation,
recruiting