Long-Term Documentation Maintenance:
Critically Necessary,
Deeply Underappreciated
Kenzie Woodbridge
I… attend meetings?
Hi! I’m Kenzie (Pronouns: They/them)
I Contribute Substantively In Meetings!
Hi! I’m Kenzie (Pronouns: They/them)
I care about documentation a lot (and talk obsessively about it in meetings)
Hi! I’m Kenzie (Pronouns: They/them)
Work at BCIT. Write and edit Docs. �Design and deliver user training. �Support and advocate for users.
Hi! I’m Kenzie (Pronouns: They/them)
Source: Geek and Poke, 2009
The dream
The Problem
Documentation is Great...
… But *ONLY* When It Is Current, Accurate, and Relevant.
And Sometimes, It Isn’t.
Definitions
What is Documentation?
“The Life-Changing Magic of Writing Things Down.”
Definitions
What is Documentation?
Developer Documentation, User Documentation, Code Comments, Knowledge Base, Code Samples, Release Notes, Embedded Help, UI Text, User Manual, Etc., Etc., Etc.
Definitions
Everything We Do To Ensure Continued Accuracy, Relevance, and Currency Of Our Documentation Over Months To Years.
What is Long-Term Maintenance?
The Hard TrutH
Technology Won’t Save Us.
I’m So Sorry.
… But, It Still Comes Down to People.
Technological Solutions Can Help…
The Plan
A. Introductions and Definitions
B. Crush Hopes and Dreams
C. What Makes a Maintenance � Strategy “Good”?
D. Strategies
E. Summary and Conclusions
F. Restore Optimism and Hope for Future� (Optional, Time-Permitting)
criteria
a good Docs maintenance strategy:
criteria
a good Docs maintenance strategy:
1. Works for the people using it
criteria
a good Docs maintenance strategy:
1. Works for the people using it
2. ensures docs remain accurate, relevant, � and current over time
criteria
a good Docs maintenance strategy:
1. Works for the people using it
2. ensures docs remain accurate, relevant, � and current over time
3. Is self-sustaining/encourages use
criteria
a good Docs maintenance strategy:
1. Works for the people using it
2. ensures docs remain accurate, relevant, � and current over time
3. Is self-sustaining/encourages use
4. Fits budgets (money, time, attention, � performance, etc.)
criteria
a good Docs maintenance strategy:
1. Works for the people using it
2. ensures docs remain accurate, relevant, � and current over time
3. Is self-sustaining/encourages use
4. Fits budgets (money, time, attention, � performance, etc.)
5. is forward-thinking and can scale as � needed
The Plan, Revisited
D. Strategies
E. Summary and Conclusions
F. Restore Optimism and Hope for Future� (Optional, Time-Permitting)
A. Introductions and Definitions
B. Crush Hopes and Dreams
C. What Makes a Maintenance � Strategy “Good”?
Docs Strategies That support maintenance:
Docs Strategies That support maintenance:
* “Self-Documenting” Code
Source: PC Weenies, 2012
“Self-Documenting” Code?
Well-Commented Code?
Can:
* Make Code Base More Maintainable
* Save Future Developer Time
* Inspire Enthusiasm
But:
* No Holistic View of Docs - Hard to Identify
Gaps, Duplications, Etc.
* Inaccessible to End Users, Limited Reusability
* Not Actually a Thing (Sorry)
* Make Outdated Info Very Unlikely
* Make Outdated Info Unlikely
* Quality Can Be Variable
Source: CommitStrip 2016
Well-Commented Code?
Write Good Code
CAN:
* Make Code Base More Maintainable
* Save Future Developer Time
* Inspire Enthusiasm
* Make Outdated Info Unlikely
BUT:
* Quality Can Be Variable
* No Holistic View of Docs - Hard to Identify
Gaps, Duplications, Etc.
* Inaccessible to End Users, Limited Reusability
Strategies That Support Maintenance:
* “Self-Documenting” Good Code
Strategies That Support Maintenance:
* “Self-Documenting” Good Code
* Structured Content
Structured Content �(Dita, etc.)
But:
* Docs Tool is Likely Completely Separate From Code Base
* Daunting For Inexperienced Writers
Can:
* Make Duplication and Inconsistency Unlikely
* Build In Holistic View of Docs
* Make Docs Easier to Update Over Time * Scale Well
Strategies That Support Maintenance:
* “Self-Documenting” Good Code
* Structured Content
Strategies That Support Maintenance:
* “Self-Documenting” Good Code
* Structured Content
* Automatic Doc Generation
Automatic Documentation �Generation
But:
* Quality is Variable and Gaps are Inevitable
* Generator is One More Thing to Maintain
Can:
* Be Just So Much Fun! (If You Are A Developer)
* Make Docs Easy to Update - Just Generate Again
* Ensure That Code Samples Are Very Likely to Actually Work
Strategies That Support Maintenance:
* “Self-Documenting” Good Code
* Structured Content
* Automatic Doc Generation
* Good Records
Strategies That Support Maintenance:
* “Self-Documenting” Good Code
* Structured Content
* Automatic Doc Generation
Good Records
Good Records
But:
* Records Are One More Thing to Maintain
* Record-Keeping is The Easiest Thing To Drop
Can:
* Make Holistic View Accessible on Demand
* Help Identify Duplications And Gaps
* Good Records
Strategies That Support Maintenance:
* “Self-Documenting” Good Code
* Structured Content
* Automatic Doc Generation
* Good Records
* Dedicated Docs Strategist/Team � Integrated with Dev Team
Strategies That Support Maintenance:
* “Self-Documenting” Good Code
* Structured Content
* Automatic Doc Generation
Docs Strategist/Team�Integrated With Devs
Docs Environment/Processes�Integrated With Dev Environment/Processes
But:
* Requires $, Organizational Will
Can:
* Maintain Good Holistic Overall View of Docs
* Deal With Gaps, Duplications, Outdated Info
* Support Devs, User Support Team, Users, etc.
* Good Records
* Dedicated Docs Strategist/Team � Integrated with Dev Team
Strategies That Support Maintenance:
* “Self-Documenting” Good Code
* Structured Content
* Automatic Doc Generation
Small Scale, Budget:
* Good Records
* Dedicated Docs Strategist/Team � Integrated with Dev Team
Strategies That Support maintenance:
* “Self-Documenting” Good Code
* Structured Content
* Automatic Doc Generation
Small Scale, Budget:
* “Let’s Go Review All The � Docs”
* Good Records
* Dedicated Docs Strategist/Team � Integrated with Dev Team
Strategies That Support maintenance:
* “Self-Documenting” Good Code
* Structured Content
* Automatic Doc Generation
“Let’s Go Review �All The Docs”
But:� * Doesn’t Scale; Time-Consuming and Onerous if Lots o’ Docs� * More Likely to be Interrupted/Not Finished� * Everyone Loves it… Until They Don’t
Can:� * Provide Good Holistic View of Docs� * Identify Gaps, Duplications, Outdated Content
Small Scale, Budget:
* “Let’s Go Review All The � Docs”
* Good Records
* Dedicated Docs Strategist/Team � Integrated with Dev Team
Strategies That Support maintenance:
* “Self-Documenting” Good Code
* Structured Content
* Automatic Doc Generation
Small Scale, Budget:
* “Let’s Go Review All The � Docs”
* User-Triggered Review/� Update
* Good Records
* Dedicated Docs Strategist/Team � Integrated with Dev Team
Strategies That Support maintenance:
* “Self-Documenting” Good Code
* Structured Content
* Automatic Doc Generation
User-triggered Review/Update
Can:
* Ensure No Wasted Work
* Prioritize Efforts
* Be Cheap/Free
But:
* Lacks Holistic View of Docs
* Can’t Identify Gaps or Duplications
* Doesn’t Really Scale
Small Scale, Budget:
* “Let’s Go Review All The � Docs”
* User-Triggered Review/� Update
* Good Records
* Dedicated Docs Strategist/Team � Integrated with Dev Team
Strategies That Support maintenance:
* “Self-Documenting” Good Code
* Structured Content
* Automatic Doc Generation
Strategies That Support maintenance:
* “Self-Documenting” Good Code
* Structured Content
* Automatic Doc Generation
* Good Records
* Dedicated Docs Strategist/Team � Integrated with Dev Team
Small Scale, Budget:
* “Let’s Go Review All The � Docs”
* User-Triggered Review/� Update
* Metrics-Directed � Review
METRICS-DIRECTED REVIEW
Top three resources:
(home page) 9.68
16.86
6.96
+ 3.81
37.25%
METRICS-DIRECTED REVIEW
But:
* Deliberately Creates Gaps * No Holistic View
* Can’t Identify Duplications, etc.
Can:
* Prioritize Efforts by User Need
* Be Efficient * Be Used At Any Scale
Small Scale, Budget:
* “Let’s Go Review All The � Docs”
* User-Triggered Review/� Update
* Metrics-Directed � Review
* Good Records
* Dedicated Docs Strategist/Team � Integrated with Dev Team
Strategies That Support maintenance:
* “Self-Documenting” Good Code
* Structured Content
* Automatic Doc Generation
Larger Scale, Budget, Period of Time, Audience, Team:
* Good Records
* Dedicated Docs Strategist/Team � Integrated with Dev Team
Strategies That Support Maintenance:
* “Self-Documenting” Good Code
* Structured Content
* Automatic Doc Generation
Small Scale, Budget:
* “Let’s Go Review All The � Docs”
* User-Triggered Review/� Update
* Metrics-Directed � Review
Larger Scale, Budget, Period of Time, Audience, Team:
* Scheduled Enforced � Review
* Good Records
* Dedicated Docs Strategist/Team � Integrated with Dev Team
Strategies That Support Maintenance:
* “Self-Documenting” Good Code
* Structured Content
* Automatic Doc Generation
Small Scale, Budget:
* “Let’s Go Review All The � Docs”
* User-Triggered Review/� Update
* Metrics-Directed � Review
Scheduled Enforced Regular review
Can:
* Make Outdated Docs Rare/Short-Lived�* Eliminate Gaps and Duplications
* Make Workload Manageable Over Time
But:
* Requires Committed Resource/s to � Support and Enforce Review
* Reliant on Good Records
Larger Scale, Budget, Period of Time, Audience, Team:
* Scheduled Enforced � Review
* Good Records
* Dedicated Docs Strategist/Team � Integrated with Dev Team
Strategies That Support Maintenance:
* “Self-Documenting” Good Code
* Structured Content
* Automatic Doc Generation
Small Scale, Budget:
* “Let’s Go Review All The � Docs”
* User-Triggered Review/� Update
* Metrics-Directed � Review
Larger Scale, Budget, Period of Time, Audience, Team:
* Scheduled Enforced � Review
* “Grand Unified Theory of
Everything”
* Good Records
* Dedicated Docs Strategist/Team � Integrated with Dev Team
Strategies That Support Maintenance:
* “Self-Documenting” Good Code
* Structured Content
* Automatic Doc Generation
Small Scale, Budget:
* “Let’s Go Review All The � Docs”
* User-Triggered Review/� Update
* Metrics-Directed � Review
“Grand Unified Theory
of Docs Maintenance”
“Grand Unified Theory
of EVERYTHING”
To start:
“Grand Unified Theory
of Docs Maintenance”
To start:
Later On:
* Keep on Enforcing Regular Review (Forever)
* Do Metrics-Directed Review (5-30 mins, Repeat)
* Look at Ensuring Good Code and Consider Using � Automatic Documentation Generator
* Consider Structured Content Approach for Docs
- Start with Docs Templates
“Grand Unified Theory
of Docs Maintenance”
But:
* Hey Presto, Complexity!
Can:
* Reinforce Each Strategy and Reward Use
* Backfill Deficiencies of Any One Strategy
* Ensure That Kanban Board Never Empties
Larger Scale, Budget, Period of Time, Audience, Team:
* Scheduled Enforced � Review
* “Grand Unified Theory of
Everything Docs
Maintenance”
Small Scale, Budget:
* “Let’s Go Review All The � Docs”
* User-Triggered Review/� Update
* Metrics-Directed � Review
* Good Records
* Dedicated Docs Strategist/Team � Integrated with Dev Team
Strategies That Support Maintenance:
* “Self-Documenting” Good Code
* Structured Content
* Automatic Doc Generation
The Plan, Revisited
D. Strategies
E. Summary and Conclusions
F. Restore Optimism and Hope for Future� (Optional, Time-Permitting)
A. Introductions and Definitions
B. Crush Hopes and Dreams
C. What Makes a Maintenance � Strategy “Good”?
?
Summary
* Scale and Resources are Important.
* Plenty of Strategies to Choose From.
* Start Now With What and Who You Have,� From Where You Are. Something > Nothing.
* Keep Going. And Good Luck!
Thank you!
These Slides:
Notes and Sources: