KEMBAR78
APItheDocs: How Can API Documentation Be Agile? | PPTX
H O W C A N A P I
D O C U M E N T A T I O N
B E C O M E
I N H E R E N T L Y
A G I L E ?
J E N N I F E R R I G G I N S @ J K R I G G I N S
# A P I T H E D O C S
H O W C A N Y O U F O S T E R
A C U L T U R E T H A T G E T S Y O U R
D E V E L O P E R S E X C I T E D A B O U T
D O C U M E N T A T I O N ?
H O W C A N Y O U F O S T E R
A C U L T U R E T H A T G E T S Y O U R
D E V E L O P E R S E X C I T E D A B O U T
P L E A S I N G T H E I R C U S T O M E R S ?
H O W C A N Y O U C O N V I N C E
A G I L E T E A M S T H E
I M P O R T A N C E O F
D O C U M E N T A T I O N ?
G A M E P L A N
• Why are docs important? What
makes good documentation? What
makes it un-agile?
• Waterfall to Agile transformation
• Kanban RICE transformation
• Scrum transformation
• Automation, Continuous
Documentation, Doc-First
• Who’s in charge?
W H Y D O P E O P L E T H I N K D O C S
A R E N ’ T A G I L E ?
W H Y A R E D O C S
R E J E C T E D ?
Feels like Waterfall, old school
Feels top-down management
Never enough time
Boring, a pain
Lack of ownership
Hot Potato Syndrome
“ I ’ V E S E E N F E W T E A M S W H O A R E
A C T U A L L Y A G I L E , W H E R E E V E R Y O N E
I S A B L E T O W O R K O N S T U F F A T T H E
S A M E T I M E , W H E R E Y O U G E T U P A N D
D O W N I N T H A T C I R C U L A R E F F E C T . I T
D O E S T E N D T O B E A S E R I E S O F M I N I -
W A T E R F A L L S . ”
@ A G I L E D O C
R O B W O O D G A T E
“ A P I D E S I G N - F I R S T I S I N H E R E N T L Y
N O T A G I L E . W E D E S I G N T H E W H O L E
T H I N G A N D T H E N T H R O W T H E
W H O L E T H I N G O V E R
[ D E C L A R I N G ] ‘ B E T H E R E C I P I E N T S
O F O U R W I S D O M ’ . ”
@ M A N P
E M M A N U E L
P A R A S K A K I S
“ T H I S I S T H E G O O D A N D B A D S I D E O F
A G I L E A U T O N O M Y … I N T H E E N D , I F I T ’ S
D O N E W I T H O U T C O N T R O L , W E W I L L H A V E
M A N Y M A N Y M I C R O S E R V I C E S T H A T
D O N ’ T S P E A K T H E S A M E L A N G U A G E A N D
I T W I L L C O S T A B U N C H O F M O N E Y . ”
@ A P I H A N D Y M A N
A R N A U D L A U R E T
“ T H E P I E C E A B O U T I T B E I N G ‘ T H E N U M B E R -
O N E T H I N G P E O P L E W A N T ’ I S N ’ T
R E G I S T E R I N G A T M O S T C O M P A N I E S I S E R V E .
N O T A L L O F T H E M A R E I N T H E O P E N - S O U R C E
S P A C E , W H E R E D O C U M E N T A T I O N T R U L Y
S E L L S T H E P R O D U C T , B U T M O S T O F M Y
C L I E N T S T H I N K A B O U T D O C U M E N T A T I O N T O O
L A T E A N D R E S I S T P A Y I N G R E S P E C T A B L E
R A T E S W H E N T H E Y F I N D T H E R A R E
C O M B I N A T I O N O F D E V E L O P E R S K I L L S A N D
T E C H N I C A L W R I T I N G T A L E N T . ”
@ S Y N E R G I S T E C H
A N D R E W D A V I S
W H A T ’ S T H E C A S E F O R A P I
D O C U M E N T A T I O N ?
W H Y D O C S ?
• Cuts customer support
• Affects decision making
• For API consumers, most important
thing
• Shows you care about DX
• Internal efficiency
• Accelerates dev onboarding
W H Y D O C S ?
• Only way to unite new developer
autonomous world of containers,
microservices and the like
• Documentation = simpler code
• Allows you to prototype, write spec
• True collaboration = truly agile
D O C U M E N T A T I O N S H O U L D F I T I N T H E A G I L E
W O R L D “ B E C A U S E Y O U H A V E T H E A B I L I T Y T O
M O D I F Y T H E T H I N G T H A T D R I V E S T H E W H O L E
P R O C E S S A T A L M O S T E V E R Y S T A G E O F
D E V E L O P M E N T . A N D T H E M O D I F I C A T I O N S C A N
A F F E C T I N A C O N T R O L L E D W A Y A L L O F T H E
A R T I F A C T S T H A T A R E D O W N S T R E A M O F I T . ”
@ F E H G U Y
T O N Y T A M
W H A T M A K E S F O R G O O D A P I
D O C U M E N T A T I O N ?
W H A T I S G O O D
D O C U M E N T A T I O N ?
• Simple, to the point
• Personal, specific to user, major personas
• Searchable
• Continuous
• Involves the consumer
• Up-to-date with versioning
• Welcoming, interactive, “you”
• Filled with examples
“ A T T H E M I C R O - L E V E L , Y O U ' R E C O N C E R N E D W I T H
E F F I C I E N C Y A N D S Y N C H R O N I Z A T I O N O F T H E A P I
D O C U M E N T A T I O N P R O C E S S : K E E P I N G T H E
D O C U M E N T A T I O N I N S Y N C W I T H A N E V O L V I N G A P I
D E S I G N , V E R I F Y I N G D O C U M E N T A T I O N A C C U R A C Y
A N D Q U A L I T Y W I T H T H E H I G H E S T P O S S I B L E
C O N F I D E N C E , W I T H T H E F A S T E S T P O S S I B L E
C Y C L E T I M E . ”
@ T E D E P S T E I N
T E D E P S T E I N
“ A T T H E M A C R O - L E V E L , W E ' R E C O N C E R N E D N O T J U S T
W I T H D O C U M E N T A T I O N A S P A R T O F T H E A P I P R O D U C T
I T S E L F , B U T A S P A R T O F T H E B R O A D E R L I F E C Y C L E T H A T
I N C L U D E S A P I L E A R N I N G , I N T E G R A T I O N A N D
F E E D B A C K F R O M C L I E N T D E V E L O P E R S , W H O A R E T H E
C O N S U M E R S O F T H E A P I . D O C U M E N T A T I O N C A N B E
C R I T I C A L I N A C C E L E R A T I N G D E V E L O P E R O N B O A R D I N G ,
A N D C R E A T I N G A N O N G O I N G , R E S P O N S I V E F E E D B A C K
L O O P . I F W E O V E R - F O C U S O N O P T I M I Z A T I O N A T T H E
M I C R O - L E V E L , W E M A Y M I S S T H E B I G G E R P I C T U R E .
D E L I V E R I N G H I G H - Q U A L I T Y D O C U M E N T A T I O N W I T H H I G H
E F F I C I E N C Y I S O N L Y M E A N I N G F U L I F T H E A P I I T S E L F
‘ C L I C K S ’ W I T H C L I E N T D E V E L O P E R S . ”
@ T E D E P S T E I N
T E D E P S T E I N
“ I F I C A N ’ T D E S C R I B E I T A N D I ’ M
W O R K I N G A R O U N D S O M E T H I N G I N
T H E D O C U M E N T A T I O N , T H E N I
N E E D T O F I X S O M E T H I N G I N T H E
C O D E . ”
@ G J T O R I K I A N
G A R E N T O R I K I A N
H O W W O R L D P A Y W E N T F R O M
W A T E R F A L L T O A G I L E
W O R L D P A Y B E F O R E
@ W O R L D P A Y _ G L O B A L
E C O M M E R C E &
P A Y M E N T S
Devs in four countries
Frustrated APIs users struggled to use
P A T H F R O M W A T E R F A L L T O A G I L E
@ C R O W H U R S T S T E L L A
S T E L L A C R O W H U R S T
1. Survey Customers
2. Work with customer service
3. Lean: What were wastes in
process?
4. Gave two in-company workshops
- User personas
- Customer journey mapping
5. Gap Analysis — what were Stripe
and Braintree doing?
L E A N C U S T O M E R J O U R N E Y M A P P I N G
Where do they need docs?
What kinds of docs do they want?
What are their pain points?
@ C R O W H U R S T S T E L L A
S T E L L A C R O W H U R S T
“ W E T H I N K T H A T I F A P R O D U C T I S D E V E L O P E D
T H E R I G H T W A Y , U S E R S S H O U L D N ’ T R E A L L Y N E E D
D O C U M E N T A T I O N , B U T I N O U R E X P E R I E N C E
P E O P L E U S U A L L Y L O O K A T D O C U M E N T A T I O N
W H E N T H E Y H A V E A P R O B L E M O R , A S
D E V E L O P E R S , I S T H E T O O L T H E Y U S E T O W O R K
O N A D A Y - T O - D A Y B A S I S T O I N T E G R A T E . S O W H A T
W E D E C I D E D T O F O C U S O N W A S I N T E G R A T I O N
D O C U M E N T A T I O N A N D F A Q T O S U P P O R T U S E R S
W H E N T H E Y H A V E P R O B L E M S . ” "
@ C R O W H U R S T S T E L L A
S T E L L A C R O W H U R S T
H O W S E N D G R I D T R A N S F O R M E D
K A N B A N W I T H R I C E
S E N D G R I D B E F O R E
@ S E N D G R I D
C U S T O M E R
C O M M U N I C A T I O N S
Docs team went agile two years ago
Two week sprints
Huge docs debt
Reactionary documentation
Constantly updating priorities
Needed to prioritize for biggest impact
Highest score, gets top building
Prioritizes Kanban backlog
Solves for urgencies
Solves for size of project
Your ability to get it DONE
Transparency
R I C E F O R M U L A =
R E A C H X I M P A C T X C O N F I D E N C E
D I V I D E D B Y
E F F O R T
@ I N T E R C O M
C U S T O M E R
C O M M U N I C A T I O N
S
@ M B E R N I E R
M A T T B E R N I E R
S E N D G R I D ’ S R I C E T W E A K S
Whole implementation took 30 minutes
RICE =
Reach X Impact X Confidence
X Business Imperative
X Due Date
divided by
Effort
Docs team +50% velocity in one month
OS team 2x velocity in one week
No more constant updating priorities
A spreadsheet calculates it all for them
3 lines in Excel > backlog in JIRA
S E N D G R I D ’ S R E S U L T S
@ M B E R N I E R
M A T T B E R N I E R
“When something doesn’t feel right?
Talk about it.”
Open-Source & Docs Teams:
“Everything can be agile.”
Efficiencies + frustrations = center
stage
Backlog transparency
S E N D G R I D ’ S R E S U L T S
@ M B E R N I E R
S C R U M : H O W C A N D O C S +
S P R I N T S E V E N W O R K ?
S H O U L D D O C S = D O N E ?
I F D O C S = S C R U M T H E N …
Start early.
Sit side by side.
Continually updated.
Can’t be shipped if not documented.
Check in with UX + DX.
It ain’t for everybody… @ A G I L E D O C
R O B W O O D G A T E
" I F O N L Y T H E D E S I G N A T E D T E C H N I C A L W R I T E R
C A N P R O D U C E T H E D O C U M E N T A T I O N , Y O U ’ R E A
S I N G L E - F U N C T I O N A L T E A M . B E A R I N M I N D T H A T
A D D I N G A N A D D I T I O N A L W R I T E R W O N ' T M A K E Y O U
S E M I - F U N C T I O N A L , B E C A U S E D O C U M E N T A T I O N
C A N ' T C O M P L E T E U N T I L T E S T I N G C O M P L E T E S , S O
A D D I N G A N O T H E R W R I T E R W I L L G I V E Y O U M O R E
M A N P O W E R , B U T I T W O N ' T C H A N G E T H E I N H E R E N T
P R O B L E M T H A T S O F T W A R E D E V E L O P M E N T I S A
L I N E A R P R O C E S S . "
@ A G I L E D O C
R O B W O O D G A T E
C A N Y O U R S C R U M T E A M … ?
Question 1: Can Anyone other than
the tech writer complete the
documentation tasks?
@ A G I L E D O C
R O B W O O D G A T E
C A N Y O U R S C R U M T E A M … ?
Question 2: What portion of the docs
can be finished quickly by tech
writer?
@ A G I L E D O C
R O B W O O D G A T E
C A N Y O U R S C R U M T E A M … ?
Question 2: What portion of the docs
can be finished quickly by tech
writer?
>75% for single functional teams
>50% for semi-functional teams
@ A G I L E D O C
R O B W O O D G A T E
C A N Y O U R S C R U M T E A M … ?
Question 3: Is the documentation
consistently high quality?
@ A G I L E D O C
R O B W O O D G A T E
C A N Y O U R S C R U M T E A M … ?
Question 4: Is there only one
deliverable?
@ A G I L E D O C
R O B W O O D G A T E
C A N Y O U R S C R U M T E A M … ?
Question 5: Do you have a docs
guide, standards and templates?
@ A G I L E D O C
R O B W O O D G A T E
C A N Y O U R S C R U M T E A M … ?
Question 6: Does your team
enhance your documentation?
@ A G I L E D O C
R O B W O O D G A T E
C A N Y O U R S C R U M T E A M … ?
If YES to most of these, you can
move toward DOCS = DONE.
@ A G I L E D O C
R O B W O O D G A T E
“ D O C U M E N T A T I O N S H O U L D
N O T B E T H E P A R T O F T H E
S O F T W A R E D E V E L O P M E N T
P R O C E S S T H A T C A U S E S Y O U
T O N O T G E T Y O U R D E F I N I T I O N
O F D O N E . ”
@ A G I L E D O C
R O B W O O D G A T E
I N S T E A D O F ‘ D O C U M E N T E D =
D O N E ’ H A V E A M I N I M A L V I A B L E
P R O D U C T O F D O C U M E N T E D
W H E R E D E V S N E E D T O
D E S C R I B E W H A T T H E Y ’ V E
C R E A T E D
@ H E L E N M U L L A L
L Y
H E L E N
M U L L A L L Y
S O , H O W C A N D O C S F U S E W I T H
A G I L E ?
D O C S C U R A T O R & S T Y L E
G U I D E
H O W D O Y O U A U T O M A T E
D O C U M E N T A T I O N P R O C E S S E S ?
C R E A T E A D U P L I C A T A B L E
P R O C E S S , T H E N A U T O M A T E I T
S O Y O U D O N ’ T M I S S A N Y T H I N G
W H E R E T O A U T O M A T E
@ C H R I S C H I N C H
C H R I S
C H I N C H I L L A
Markdown-Spellcheck
Doc style guide + quick reference list
Code example testing
Screenshot automation of successful
tests
“ O N E O F T H E T H I N G S T H A T W E
Q U I C K L Y R E A L I Z E D W E C O U L D N ’ T
D O W A S C R E A T E D O C U M E N T A T I O N
T H A T L I V E D A P A R T F R O M O U R
C O D E . I T H A D T O L I V E D I R E C T L Y
A L O N G S I D E O U R C O D E O R I T ’ D B E
I M M E D I A T E L Y O U T O F D A T E . ”
@ R V I S O T C K Y
R I C H V I S O T C K Y
D R Y P R I N C I P L E
= D O N ’ T R E P E A T Y O U R S E L F
@ T E D E P S T E I N
T E D E P S T E I N
D O C U M E N T A T I O N = D I S C I P L I N E
@ J K R I G G I N S
J E N N I F E R
R I G G I N S
T H E P I E C E S O F T H E C H A N G I N G
D E V E L O P M E N T C Y C L E L I K E
C O N T A I N E R S A N D
M I C R O S E R V I C E S T H A T M A K E
D O C U M E N T A T I O N L E S S L I K E L Y
M E A N S I T ’ S A C T U A L L Y M O R E
N E C E S S A R Y . B U T T H E S E C A N A L L
L E A D T O E V E N B E T T E R , C O -
O W N E D D O C U M E N T A T I O N .
@ J K R I G G I N S
J E N N I F E R
R I G G I N S
H O W D O Y O U J U S T G E T
S T A R T E D ?
T R Y S I T T I N G D O W N W I T H Y O U R
D E V E L O P E R S
@ J K R I G G I N S
J E N N I F E R
R I G G I N S
A G I L E D O C U M E N T A T I O N
= B E T T E R T E A M S
Everyone takes charge of own piece.
Everyone wants simple, explanatory
code (not self-explanatory.)
Individual developer can still be
creative, but has to communicate.
@ J K R I G G I N S
J E N N I F E R
R I G G I N S
W H A T S T E P S W I L L Y O U T A K E ?
J E N N I F E R R I G G I N S @ J K R I G G I N S
# A P I T H E D O C S
T H A N K S T O N E W O L D S T O C K F O R I M A G E S

APItheDocs: How Can API Documentation Be Agile?

  • 1.
    H O WC A N A P I D O C U M E N T A T I O N B E C O M E I N H E R E N T L Y A G I L E ? J E N N I F E R R I G G I N S @ J K R I G G I N S # A P I T H E D O C S
  • 2.
    H O WC A N Y O U F O S T E R A C U L T U R E T H A T G E T S Y O U R D E V E L O P E R S E X C I T E D A B O U T D O C U M E N T A T I O N ?
  • 3.
    H O WC A N Y O U F O S T E R A C U L T U R E T H A T G E T S Y O U R D E V E L O P E R S E X C I T E D A B O U T P L E A S I N G T H E I R C U S T O M E R S ?
  • 4.
    H O WC A N Y O U C O N V I N C E A G I L E T E A M S T H E I M P O R T A N C E O F D O C U M E N T A T I O N ?
  • 5.
    G A ME P L A N • Why are docs important? What makes good documentation? What makes it un-agile? • Waterfall to Agile transformation • Kanban RICE transformation • Scrum transformation • Automation, Continuous Documentation, Doc-First • Who’s in charge?
  • 6.
    W H YD O P E O P L E T H I N K D O C S A R E N ’ T A G I L E ?
  • 7.
    W H YA R E D O C S R E J E C T E D ? Feels like Waterfall, old school Feels top-down management Never enough time Boring, a pain Lack of ownership Hot Potato Syndrome
  • 8.
    “ I ’V E S E E N F E W T E A M S W H O A R E A C T U A L L Y A G I L E , W H E R E E V E R Y O N E I S A B L E T O W O R K O N S T U F F A T T H E S A M E T I M E , W H E R E Y O U G E T U P A N D D O W N I N T H A T C I R C U L A R E F F E C T . I T D O E S T E N D T O B E A S E R I E S O F M I N I - W A T E R F A L L S . ” @ A G I L E D O C R O B W O O D G A T E
  • 9.
    “ A PI D E S I G N - F I R S T I S I N H E R E N T L Y N O T A G I L E . W E D E S I G N T H E W H O L E T H I N G A N D T H E N T H R O W T H E W H O L E T H I N G O V E R [ D E C L A R I N G ] ‘ B E T H E R E C I P I E N T S O F O U R W I S D O M ’ . ” @ M A N P E M M A N U E L P A R A S K A K I S
  • 10.
    “ T HI S I S T H E G O O D A N D B A D S I D E O F A G I L E A U T O N O M Y … I N T H E E N D , I F I T ’ S D O N E W I T H O U T C O N T R O L , W E W I L L H A V E M A N Y M A N Y M I C R O S E R V I C E S T H A T D O N ’ T S P E A K T H E S A M E L A N G U A G E A N D I T W I L L C O S T A B U N C H O F M O N E Y . ” @ A P I H A N D Y M A N A R N A U D L A U R E T
  • 11.
    “ T HE P I E C E A B O U T I T B E I N G ‘ T H E N U M B E R - O N E T H I N G P E O P L E W A N T ’ I S N ’ T R E G I S T E R I N G A T M O S T C O M P A N I E S I S E R V E . N O T A L L O F T H E M A R E I N T H E O P E N - S O U R C E S P A C E , W H E R E D O C U M E N T A T I O N T R U L Y S E L L S T H E P R O D U C T , B U T M O S T O F M Y C L I E N T S T H I N K A B O U T D O C U M E N T A T I O N T O O L A T E A N D R E S I S T P A Y I N G R E S P E C T A B L E R A T E S W H E N T H E Y F I N D T H E R A R E C O M B I N A T I O N O F D E V E L O P E R S K I L L S A N D T E C H N I C A L W R I T I N G T A L E N T . ” @ S Y N E R G I S T E C H A N D R E W D A V I S
  • 12.
    W H AT ’ S T H E C A S E F O R A P I D O C U M E N T A T I O N ?
  • 13.
    W H YD O C S ? • Cuts customer support • Affects decision making • For API consumers, most important thing • Shows you care about DX • Internal efficiency • Accelerates dev onboarding
  • 14.
    W H YD O C S ? • Only way to unite new developer autonomous world of containers, microservices and the like • Documentation = simpler code • Allows you to prototype, write spec • True collaboration = truly agile
  • 15.
    D O CU M E N T A T I O N S H O U L D F I T I N T H E A G I L E W O R L D “ B E C A U S E Y O U H A V E T H E A B I L I T Y T O M O D I F Y T H E T H I N G T H A T D R I V E S T H E W H O L E P R O C E S S A T A L M O S T E V E R Y S T A G E O F D E V E L O P M E N T . A N D T H E M O D I F I C A T I O N S C A N A F F E C T I N A C O N T R O L L E D W A Y A L L O F T H E A R T I F A C T S T H A T A R E D O W N S T R E A M O F I T . ” @ F E H G U Y T O N Y T A M
  • 16.
    W H AT M A K E S F O R G O O D A P I D O C U M E N T A T I O N ?
  • 17.
    W H AT I S G O O D D O C U M E N T A T I O N ? • Simple, to the point • Personal, specific to user, major personas • Searchable • Continuous • Involves the consumer • Up-to-date with versioning • Welcoming, interactive, “you” • Filled with examples
  • 18.
    “ A TT H E M I C R O - L E V E L , Y O U ' R E C O N C E R N E D W I T H E F F I C I E N C Y A N D S Y N C H R O N I Z A T I O N O F T H E A P I D O C U M E N T A T I O N P R O C E S S : K E E P I N G T H E D O C U M E N T A T I O N I N S Y N C W I T H A N E V O L V I N G A P I D E S I G N , V E R I F Y I N G D O C U M E N T A T I O N A C C U R A C Y A N D Q U A L I T Y W I T H T H E H I G H E S T P O S S I B L E C O N F I D E N C E , W I T H T H E F A S T E S T P O S S I B L E C Y C L E T I M E . ” @ T E D E P S T E I N T E D E P S T E I N
  • 19.
    “ A TT H E M A C R O - L E V E L , W E ' R E C O N C E R N E D N O T J U S T W I T H D O C U M E N T A T I O N A S P A R T O F T H E A P I P R O D U C T I T S E L F , B U T A S P A R T O F T H E B R O A D E R L I F E C Y C L E T H A T I N C L U D E S A P I L E A R N I N G , I N T E G R A T I O N A N D F E E D B A C K F R O M C L I E N T D E V E L O P E R S , W H O A R E T H E C O N S U M E R S O F T H E A P I . D O C U M E N T A T I O N C A N B E C R I T I C A L I N A C C E L E R A T I N G D E V E L O P E R O N B O A R D I N G , A N D C R E A T I N G A N O N G O I N G , R E S P O N S I V E F E E D B A C K L O O P . I F W E O V E R - F O C U S O N O P T I M I Z A T I O N A T T H E M I C R O - L E V E L , W E M A Y M I S S T H E B I G G E R P I C T U R E . D E L I V E R I N G H I G H - Q U A L I T Y D O C U M E N T A T I O N W I T H H I G H E F F I C I E N C Y I S O N L Y M E A N I N G F U L I F T H E A P I I T S E L F ‘ C L I C K S ’ W I T H C L I E N T D E V E L O P E R S . ” @ T E D E P S T E I N T E D E P S T E I N
  • 20.
    “ I FI C A N ’ T D E S C R I B E I T A N D I ’ M W O R K I N G A R O U N D S O M E T H I N G I N T H E D O C U M E N T A T I O N , T H E N I N E E D T O F I X S O M E T H I N G I N T H E C O D E . ” @ G J T O R I K I A N G A R E N T O R I K I A N
  • 21.
    H O WW O R L D P A Y W E N T F R O M W A T E R F A L L T O A G I L E
  • 22.
    W O RL D P A Y B E F O R E @ W O R L D P A Y _ G L O B A L E C O M M E R C E & P A Y M E N T S Devs in four countries Frustrated APIs users struggled to use
  • 23.
    P A TH F R O M W A T E R F A L L T O A G I L E @ C R O W H U R S T S T E L L A S T E L L A C R O W H U R S T 1. Survey Customers 2. Work with customer service 3. Lean: What were wastes in process? 4. Gave two in-company workshops - User personas - Customer journey mapping 5. Gap Analysis — what were Stripe and Braintree doing?
  • 24.
    L E AN C U S T O M E R J O U R N E Y M A P P I N G Where do they need docs? What kinds of docs do they want? What are their pain points? @ C R O W H U R S T S T E L L A S T E L L A C R O W H U R S T
  • 25.
    “ W ET H I N K T H A T I F A P R O D U C T I S D E V E L O P E D T H E R I G H T W A Y , U S E R S S H O U L D N ’ T R E A L L Y N E E D D O C U M E N T A T I O N , B U T I N O U R E X P E R I E N C E P E O P L E U S U A L L Y L O O K A T D O C U M E N T A T I O N W H E N T H E Y H A V E A P R O B L E M O R , A S D E V E L O P E R S , I S T H E T O O L T H E Y U S E T O W O R K O N A D A Y - T O - D A Y B A S I S T O I N T E G R A T E . S O W H A T W E D E C I D E D T O F O C U S O N W A S I N T E G R A T I O N D O C U M E N T A T I O N A N D F A Q T O S U P P O R T U S E R S W H E N T H E Y H A V E P R O B L E M S . ” " @ C R O W H U R S T S T E L L A S T E L L A C R O W H U R S T
  • 26.
    H O WS E N D G R I D T R A N S F O R M E D K A N B A N W I T H R I C E
  • 27.
    S E ND G R I D B E F O R E @ S E N D G R I D C U S T O M E R C O M M U N I C A T I O N S Docs team went agile two years ago Two week sprints Huge docs debt Reactionary documentation Constantly updating priorities Needed to prioritize for biggest impact
  • 28.
    Highest score, getstop building Prioritizes Kanban backlog Solves for urgencies Solves for size of project Your ability to get it DONE Transparency R I C E F O R M U L A = R E A C H X I M P A C T X C O N F I D E N C E D I V I D E D B Y E F F O R T @ I N T E R C O M C U S T O M E R C O M M U N I C A T I O N S
  • 29.
    @ M BE R N I E R M A T T B E R N I E R S E N D G R I D ’ S R I C E T W E A K S Whole implementation took 30 minutes RICE = Reach X Impact X Confidence X Business Imperative X Due Date divided by Effort
  • 30.
    Docs team +50%velocity in one month OS team 2x velocity in one week No more constant updating priorities A spreadsheet calculates it all for them 3 lines in Excel > backlog in JIRA S E N D G R I D ’ S R E S U L T S @ M B E R N I E R M A T T B E R N I E R
  • 31.
    “When something doesn’tfeel right? Talk about it.” Open-Source & Docs Teams: “Everything can be agile.” Efficiencies + frustrations = center stage Backlog transparency S E N D G R I D ’ S R E S U L T S @ M B E R N I E R
  • 32.
    S C RU M : H O W C A N D O C S + S P R I N T S E V E N W O R K ?
  • 33.
    S H OU L D D O C S = D O N E ?
  • 34.
    I F DO C S = S C R U M T H E N … Start early. Sit side by side. Continually updated. Can’t be shipped if not documented. Check in with UX + DX. It ain’t for everybody… @ A G I L E D O C R O B W O O D G A T E
  • 35.
    " I FO N L Y T H E D E S I G N A T E D T E C H N I C A L W R I T E R C A N P R O D U C E T H E D O C U M E N T A T I O N , Y O U ’ R E A S I N G L E - F U N C T I O N A L T E A M . B E A R I N M I N D T H A T A D D I N G A N A D D I T I O N A L W R I T E R W O N ' T M A K E Y O U S E M I - F U N C T I O N A L , B E C A U S E D O C U M E N T A T I O N C A N ' T C O M P L E T E U N T I L T E S T I N G C O M P L E T E S , S O A D D I N G A N O T H E R W R I T E R W I L L G I V E Y O U M O R E M A N P O W E R , B U T I T W O N ' T C H A N G E T H E I N H E R E N T P R O B L E M T H A T S O F T W A R E D E V E L O P M E N T I S A L I N E A R P R O C E S S . " @ A G I L E D O C R O B W O O D G A T E
  • 36.
    C A NY O U R S C R U M T E A M … ? Question 1: Can Anyone other than the tech writer complete the documentation tasks? @ A G I L E D O C R O B W O O D G A T E
  • 37.
    C A NY O U R S C R U M T E A M … ? Question 2: What portion of the docs can be finished quickly by tech writer? @ A G I L E D O C R O B W O O D G A T E
  • 38.
    C A NY O U R S C R U M T E A M … ? Question 2: What portion of the docs can be finished quickly by tech writer? >75% for single functional teams >50% for semi-functional teams @ A G I L E D O C R O B W O O D G A T E
  • 39.
    C A NY O U R S C R U M T E A M … ? Question 3: Is the documentation consistently high quality? @ A G I L E D O C R O B W O O D G A T E
  • 40.
    C A NY O U R S C R U M T E A M … ? Question 4: Is there only one deliverable? @ A G I L E D O C R O B W O O D G A T E
  • 41.
    C A NY O U R S C R U M T E A M … ? Question 5: Do you have a docs guide, standards and templates? @ A G I L E D O C R O B W O O D G A T E
  • 42.
    C A NY O U R S C R U M T E A M … ? Question 6: Does your team enhance your documentation? @ A G I L E D O C R O B W O O D G A T E
  • 43.
    C A NY O U R S C R U M T E A M … ? If YES to most of these, you can move toward DOCS = DONE. @ A G I L E D O C R O B W O O D G A T E
  • 44.
    “ D OC U M E N T A T I O N S H O U L D N O T B E T H E P A R T O F T H E S O F T W A R E D E V E L O P M E N T P R O C E S S T H A T C A U S E S Y O U T O N O T G E T Y O U R D E F I N I T I O N O F D O N E . ” @ A G I L E D O C R O B W O O D G A T E
  • 45.
    I N ST E A D O F ‘ D O C U M E N T E D = D O N E ’ H A V E A M I N I M A L V I A B L E P R O D U C T O F D O C U M E N T E D W H E R E D E V S N E E D T O D E S C R I B E W H A T T H E Y ’ V E C R E A T E D @ H E L E N M U L L A L L Y H E L E N M U L L A L L Y
  • 46.
    S O ,H O W C A N D O C S F U S E W I T H A G I L E ?
  • 47.
    D O CS C U R A T O R & S T Y L E G U I D E
  • 48.
    H O WD O Y O U A U T O M A T E D O C U M E N T A T I O N P R O C E S S E S ?
  • 49.
    C R EA T E A D U P L I C A T A B L E P R O C E S S , T H E N A U T O M A T E I T S O Y O U D O N ’ T M I S S A N Y T H I N G
  • 50.
    W H ER E T O A U T O M A T E @ C H R I S C H I N C H C H R I S C H I N C H I L L A Markdown-Spellcheck Doc style guide + quick reference list Code example testing Screenshot automation of successful tests
  • 51.
    “ O NE O F T H E T H I N G S T H A T W E Q U I C K L Y R E A L I Z E D W E C O U L D N ’ T D O W A S C R E A T E D O C U M E N T A T I O N T H A T L I V E D A P A R T F R O M O U R C O D E . I T H A D T O L I V E D I R E C T L Y A L O N G S I D E O U R C O D E O R I T ’ D B E I M M E D I A T E L Y O U T O F D A T E . ” @ R V I S O T C K Y R I C H V I S O T C K Y
  • 52.
    D R YP R I N C I P L E = D O N ’ T R E P E A T Y O U R S E L F @ T E D E P S T E I N T E D E P S T E I N
  • 53.
    D O CU M E N T A T I O N = D I S C I P L I N E @ J K R I G G I N S J E N N I F E R R I G G I N S
  • 54.
    T H EP I E C E S O F T H E C H A N G I N G D E V E L O P M E N T C Y C L E L I K E C O N T A I N E R S A N D M I C R O S E R V I C E S T H A T M A K E D O C U M E N T A T I O N L E S S L I K E L Y M E A N S I T ’ S A C T U A L L Y M O R E N E C E S S A R Y . B U T T H E S E C A N A L L L E A D T O E V E N B E T T E R , C O - O W N E D D O C U M E N T A T I O N . @ J K R I G G I N S J E N N I F E R R I G G I N S
  • 55.
    H O WD O Y O U J U S T G E T S T A R T E D ? T R Y S I T T I N G D O W N W I T H Y O U R D E V E L O P E R S @ J K R I G G I N S J E N N I F E R R I G G I N S
  • 56.
    A G IL E D O C U M E N T A T I O N = B E T T E R T E A M S Everyone takes charge of own piece. Everyone wants simple, explanatory code (not self-explanatory.) Individual developer can still be creative, but has to communicate. @ J K R I G G I N S J E N N I F E R R I G G I N S
  • 57.
    W H AT S T E P S W I L L Y O U T A K E ? J E N N I F E R R I G G I N S @ J K R I G G I N S # A P I T H E D O C S T H A N K S T O N E W O L D S T O C K F O R I M A G E S

Editor's Notes

  • #5 And it doesn’t slow you down
  • #8  Or a top-down management approach?
  • #9 ROB WOODGATE agile docs consultant
  • #10  Emmanuel Paraskakis, head of product development at APIary (currently being acquired by Oracle). Which is why I argue Doc-first APIs not APIs first. In fact I argue a move toward continuous documentation and even Docs-first
  • #11 Arnaud
  • #12 Andrew Davis
  • #14 ask screen before But isn’t Documentation just a vestige of waterfall? Soaked man Or a top-down management approach?
  • #16 Of course Tony Tam is biased as the inventor of Swagger but you get the idea Documentation should fit in the agile world “because you have the ability to modify the thing that drives the whole process at almost every stage of development. And the modifications can affect in a controlled way all of the artifacts that are downstream of it.”
  • #18  ADD MORE
  • #24 Like Rosalie did at gov.uk, Stella surveyed her customers
  • #26 “We think that if a product is developed the right way, users shouldn’t really need documentation, but in our experience people usually look at documentation when they have a problem or, as developers, is the tool they use to work on a day-to-day basis to integrate. So what we decided to focus on was integration documentation and FAQ to support users when they have problems.”"
  • #28 documentation became reactionary to support team needs never felt like they are getting anything done, never finishing a sprint
  • #29 Add intercom logo highest RICE score gets top billing — and then gives us the opportunity to communicate with the rest of the business to know priority — number 5 vs 22 — if you as the requester can give us more info we can raise our confidence level which will push it up in the backlog Kanban means constantly updating priorities Sendgrid just use a spreadsheet, sorting based on RICE score and formula
  • #30 rice formula= reach X impact x confidence divided by effort we tend to question our process a lot and what can we automate three sentences of spreadsheet vs backlog form in JIRA looking for little efficiencies and frustrations to optimize
  • #31 quantifiable
  • #32 cultural we tend to question our process a lot and what can we automate three sentences of spreadsheet vs backlog form in JIRA looking for little efficiencies and frustrations to optimize
  • #36 ROB WOODGATE agile docs consultant
  • #38  >75% for single functional teams >50% for semi-functional teams
  • #39  >75% for single functional teams >50% for semi-functional teams
  • #40 Question 3: Is the documentation consistently high quality? (something that shows haphazard and fast)
  • #42 Question 5: Do you have a docs guide, standards and templates?
  • #43 Question 5: Do you have a docs guide, standards and templates?
  • #45 “Documentation should not be the part of the software development process that causes you to not get your definition of done.”
  • #46 Instead of ‘documented = done’ have a minimal viable product of documented where devs need to describe what they’ve created Helen Mullally
  • #49 In the end, docs are boring and often repeatable, so you want to automate the crap out of it
  • #50 humans aren’t very good at repeatable tasks, but machines are
  • #51 uses open source dictionary files. Adjust your script to your preferences (e.g. report mode, ignore numbers and acronyms). Create a separate repository with the typical custom language (not a real word, but not wrong), so they won't get flagged by the checker. Decide what to let through. Can add to your own dictionary, customize for words that aren’t real words but aren’t wrong and integrate with even Open Office
  • #52 Agile Coach Rich
  • #54 What interruptions are constantly pointed to as excuses for not completing doc address repeated issues with automation
  • #55 The pieces of the changing development cycle like containers that makes documentation less likely but more necessary can be used for great documentation
  • #56 The pieces of the changing development cycle like containers that makes documentation less likely but more necessary can be used for great documentation