KEMBAR78
APItheDocs: How Can API Documentation Be Agile? | PPTX
eBranding Ninja, profile picture
Uploaded byeBranding Ninja
PPTX, PDF3,620 views

APItheDocs: How Can API Documentation Be Agile?

The document discusses the importance of agile documentation, highlighting how effective documentation can enhance developer satisfaction and customer experience. It outlines the challenges faced during the transition from waterfall to agile methodologies, emphasizing the need for continuous documentation that evolves with the development process. Strategies such as user persona mapping, customer journey analysis, and prioritizing documentation tasks based on their impact and urgency are also presented as ways to foster a culture of agile documentation.

Download to read offline
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

More Related Content

PPTX
How can documentation become inherently Agile?
byeBranding Ninja
 
PPTX
Social Media, Keeping up to date, Pure and more : The Leiden talk
byGuus van den Brekel
 
PDF
Tech rfp template
byAnna Duin
 
PDF
Making Peace: Resolving the Content/ UX Tug-of-War in Responsive Web Design
byJenny Magic
 
PPTX
Interactive media : information and libraries (#bobcatsss2017)
byGuus van den Brekel
 
PDF
Social media creates social power
byStephanie G. Brooks
 
PDF
Mobile Resources Use in a Distance Learning Population
byBillie Anne Gebb
 
PDF
Un-artificial intelligence
byMelinda Seckington
 
How can documentation become inherently Agile?
byeBranding Ninja
 
Social Media, Keeping up to date, Pure and more : The Leiden talk
byGuus van den Brekel
 
Tech rfp template
byAnna Duin
 
Making Peace: Resolving the Content/ UX Tug-of-War in Responsive Web Design
byJenny Magic
 
Interactive media : information and libraries (#bobcatsss2017)
byGuus van den Brekel
 
Social media creates social power
byStephanie G. Brooks
 
Mobile Resources Use in a Distance Learning Population
byBillie Anne Gebb
 
Un-artificial intelligence
byMelinda Seckington
 

What's hot

PDF
Un-artificial Intelligence: How People Learn (Melinda Seckington)
byFuture Insights
 
PDF
SearchLove London | Kelvin Newman, 'What the Flash Crash and Black Boxes can ...
byDistilled
 
PDF
Alvis ownership-knowledge
byLeo Bekhuis
 
PDF
Cultivating Campus Collaborations
bychar booth
 
PPTX
Altmetrics in UMCG : pilot and update
byCentrale Medische Bibliotheek, Universitair Medisch Centrum Groningen (UMCG)
 
PDF
Project Management & Innovation
bymade4gov
 
PDF
Steps and Plan for Recruitment using Social Media
byDivyanshiJoshi
 
PDF
Why Reflect? The Holistic Practice of Stepping Back.
bychar booth
 
PDF
Film240 Flipbook
byHolly Macdonald
 
PPTX
SharePoint Saturday Redmond - Building solutions with the future in mind
byChris Johnson
 
PDF
Data Visualizations in Digital Products (ProductCamp Boston 2016)
byProductCamp Boston
 
PDF
Rp2-2015 - Experience - Tools n Methods
byRavi Pal
 
PDF
The Ethics of Everybody Else
byTyler Schnoebelen
 
PDF
BIMA + Creative Equals Evening Masterclass: How to Shape Great Creative
byBIMA (British Interactive Media Association)
 
PDF
Technology Trends, Consumer Experience @MICA 2016
byRavi Pal
 
PDF
FSLSO QTR
byGilberto Parada
 
PDF
Thinking like a Network
byJonas Altman
 
PDF
Growth Framework for Consumer Startups
byP J
 
PDF
#Winning at Instagram, or How to Learn to Stop Worrying and Love the Algorithm
byKate O'Neill
 
PDF
Rp2-2015-technology trends enriching consumer experience
byRavi Pal
 
Un-artificial Intelligence: How People Learn (Melinda Seckington)
byFuture Insights
 
SearchLove London | Kelvin Newman, 'What the Flash Crash and Black Boxes can ...
byDistilled
 
Alvis ownership-knowledge
byLeo Bekhuis
 
Cultivating Campus Collaborations
bychar booth
 
Altmetrics in UMCG : pilot and update
byCentrale Medische Bibliotheek, Universitair Medisch Centrum Groningen (UMCG)
 
Project Management & Innovation
bymade4gov
 
Steps and Plan for Recruitment using Social Media
byDivyanshiJoshi
 
Why Reflect? The Holistic Practice of Stepping Back.
bychar booth
 
Film240 Flipbook
byHolly Macdonald
 
SharePoint Saturday Redmond - Building solutions with the future in mind
byChris Johnson
 
Data Visualizations in Digital Products (ProductCamp Boston 2016)
byProductCamp Boston
 
Rp2-2015 - Experience - Tools n Methods
byRavi Pal
 
The Ethics of Everybody Else
byTyler Schnoebelen
 
BIMA + Creative Equals Evening Masterclass: How to Shape Great Creative
byBIMA (British Interactive Media Association)
 
Technology Trends, Consumer Experience @MICA 2016
byRavi Pal
 
FSLSO QTR
byGilberto Parada
 
Thinking like a Network
byJonas Altman
 
Growth Framework for Consumer Startups
byP J
 
#Winning at Instagram, or How to Learn to Stop Worrying and Love the Algorithm
byKate O'Neill
 
Rp2-2015-technology trends enriching consumer experience
byRavi Pal
 

Similar to APItheDocs: How Can API Documentation Be Agile?

PDF
The road to front-end mastery
byBobby van der Sluis
 
PDF
Things We're Still Figuring Out
byAuthentic Form & Function
 
PDF
Why you need excellent documents and how to produce them… with Enterprise Arc...
byeaDocX
 
PDF
Franchisee Business Proposal
byPRSInternational1
 
PDF
Continuous Discovery is it future of Continuous Delivery.pdf
byBruno Boucard
 
PPTX
Nasscom agile methodology-pitneybowe-jai
byJainendra Kumar
 
PDF
Agile NCR 2013- Jainendra Kumar - agilemethodology-pitneybowe-jai1
byAgileNCR2013
 
PDF
Josh Griffin - Examples of Work
byJoshua Griffin
 
PPTX
Its the Product. Not the Project May 17 2017
byKathleen Leach, PMP
 
PPTX
Its the Product Not the Project may 17 2017
byPM Reston Luncheon Series (PMIWDC)
 
PDF
Agile certification integrated services faq
byjohnlucy
 
PDF
Agile certification integrated services faq
byjohnlucy
 
PDF
Chris Girolamo It's the Product not the Project 19 Mar 14
byLianaEliz222
 
PDF
Scrum at Scale
bySalesforce Engineering
 
PDF
Codecademy Live QA Presentation
byJames Kim
 
PDF
Intergen Twilight - Corralling the Document Chaos
byIntergen
 
PDF
Feels.js
byFITC
 
PDF
What Officience Outsourcing team does
byThanh An LE NGUYEN
 
PDF
Selling lean development
bywozmir
 
PDF
Is Agile Documentation An Oxymoron?
byKurt Solarte
 
The road to front-end mastery
byBobby van der Sluis
 
Things We're Still Figuring Out
byAuthentic Form & Function
 
Why you need excellent documents and how to produce them… with Enterprise Arc...
byeaDocX
 
Franchisee Business Proposal
byPRSInternational1
 
Continuous Discovery is it future of Continuous Delivery.pdf
byBruno Boucard
 
Nasscom agile methodology-pitneybowe-jai
byJainendra Kumar
 
Agile NCR 2013- Jainendra Kumar - agilemethodology-pitneybowe-jai1
byAgileNCR2013
 
Josh Griffin - Examples of Work
byJoshua Griffin
 
Its the Product. Not the Project May 17 2017
byKathleen Leach, PMP
 
Its the Product Not the Project may 17 2017
byPM Reston Luncheon Series (PMIWDC)
 
Agile certification integrated services faq
byjohnlucy
 
Agile certification integrated services faq
byjohnlucy
 
Chris Girolamo It's the Product not the Project 19 Mar 14
byLianaEliz222
 
Scrum at Scale
bySalesforce Engineering
 
Codecademy Live QA Presentation
byJames Kim
 
Intergen Twilight - Corralling the Document Chaos
byIntergen
 
Feels.js
byFITC
 
What Officience Outsourcing team does
byThanh An LE NGUYEN
 
Selling lean development
bywozmir
 
Is Agile Documentation An Oxymoron?
byKurt Solarte
 

More from eBranding Ninja

PPTX
How (and why) to Factor Tech Ethics into Your Sprint
byeBranding Ninja
 
PPTX
Personal Branding for Women in Tech
byeBranding Ninja
 
PPTX
How Chatbots will overtake the app in 2017
byeBranding Ninja
 
PPTX
Merit Money: Motivation Beats Traditional Bonus System
byeBranding Ninja
 
PPTX
What is Personal Branding? A Starter Guide
byeBranding Ninja
 
PPTX
How to Make LinkedIn Work for You
byeBranding Ninja
 
PPTX
How to Pitch Like a Rockstar
byeBranding Ninja
 
How (and why) to Factor Tech Ethics into Your Sprint
byeBranding Ninja
 
Personal Branding for Women in Tech
byeBranding Ninja
 
How Chatbots will overtake the app in 2017
byeBranding Ninja
 
Merit Money: Motivation Beats Traditional Bonus System
byeBranding Ninja
 
What is Personal Branding? A Starter Guide
byeBranding Ninja
 
How to Make LinkedIn Work for You
byeBranding Ninja
 
How to Pitch Like a Rockstar
byeBranding Ninja
 

Recently uploaded

PPTX
"The Art of Web Scraping: Tree Algorithms and JS Magic", Dmytro Tarasenko
byFwdays
 
PPTX
BioVault.net ADW 2025 CODATA: SyftBox: a General Purpose Solution for Data Vi...
byMadhava Jay
 
PPTX
WUG-DMV: Workfront Wizards: Tips & Tricks Exchange (Sept 2025)
byWUG-DC MARYLAND VIRGINIA
 
PDF
AGV PROTOCOL BRAND KIT COMPLETE VIEW.pdf
byfagbolade
 
PDF
From Data Chaos to Copilot Confidence: A Step-by-Step Microsoft 365 Copilot R...
byNikki Chapple
 
PDF
Application Monitoring and Observability: Elastic Stack Solution for Producti...
byPattabhi Amperayani
 
PDF
A 4-Terminal Approach to Validating Charge Conservation in MOSFET Compact Models
byEalwan Lee
 
PDF
Agentic AI Guide for Enterprise Use-cases
byDebmalya Biswas
 
PDF
Ethical Initiatives in AI and accountability.pdf
byShiwani Gupta
 
PPTX
Hybrid Active Directory Cyber Resiliency
byFrancesco Faenzi
 
PDF
Session 4 - Specialized AI Associate Series: UiPath Document Understanding O...
byDianaGray10
 
PPTX
Session 5 - Specialized AI Associate Series: Build a Document Understanding ...
byDianaGray10
 
PPTX
"Towards React Server Components in Clojure", Roman Liutikov
byFwdays
 
PDF
Planetek Italia Corporate Profile brochure
byPlanetek Italia Srl
 
PDF
Session 2 - Agentic Orchestration with UiPath Maestro
byDianaGray10
 
PPTX
Agentic AI Solutions and Services | Aeologic
byankitaeologic
 
PDF
UiPath DevConnect 2025: Introduction to Agentic Automation
byDianaGray10
 
PDF
A fool with a tool is still a fool - Plone Conference 2025
byAndreas Jung
 
PPTX
CBD Belgium 2025 - The adventures of a Microsoft 365 Platform Owner.pptx
byJasper Oosterveld
 
PDF
KV Caching Strategies for Latency-Critical LLM Applications by John Thomson
byScyllaDB
 
"The Art of Web Scraping: Tree Algorithms and JS Magic", Dmytro Tarasenko
byFwdays
 
BioVault.net ADW 2025 CODATA: SyftBox: a General Purpose Solution for Data Vi...
byMadhava Jay
 
WUG-DMV: Workfront Wizards: Tips & Tricks Exchange (Sept 2025)
byWUG-DC MARYLAND VIRGINIA
 
AGV PROTOCOL BRAND KIT COMPLETE VIEW.pdf
byfagbolade
 
From Data Chaos to Copilot Confidence: A Step-by-Step Microsoft 365 Copilot R...
byNikki Chapple
 
Application Monitoring and Observability: Elastic Stack Solution for Producti...
byPattabhi Amperayani
 
A 4-Terminal Approach to Validating Charge Conservation in MOSFET Compact Models
byEalwan Lee
 
Agentic AI Guide for Enterprise Use-cases
byDebmalya Biswas
 
Ethical Initiatives in AI and accountability.pdf
byShiwani Gupta
 
Hybrid Active Directory Cyber Resiliency
byFrancesco Faenzi
 
Session 4 - Specialized AI Associate Series: UiPath Document Understanding O...
byDianaGray10
 
Session 5 - Specialized AI Associate Series: Build a Document Understanding ...
byDianaGray10
 
"Towards React Server Components in Clojure", Roman Liutikov
byFwdays
 
Planetek Italia Corporate Profile brochure
byPlanetek Italia Srl
 
Session 2 - Agentic Orchestration with UiPath Maestro
byDianaGray10
 
Agentic AI Solutions and Services | Aeologic
byankitaeologic
 
UiPath DevConnect 2025: Introduction to Agentic Automation
byDianaGray10
 
A fool with a tool is still a fool - Plone Conference 2025
byAndreas Jung
 
CBD Belgium 2025 - The adventures of a Microsoft 365 Platform Owner.pptx
byJasper Oosterveld
 
KV Caching Strategies for Latency-Critical LLM Applications by John Thomson
byScyllaDB
 

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