How (not) to document
79
// // Dear maintainer: // // Once you are done trying to 'optimize' this routine, // and have realized what a terrible mistake that was, // please increment the following counter as a warning // to the next guy: // // total_hours_wasted_here = 42 //
-
Upload
janos-pasztor -
Category
Technology
-
view
225 -
download
2
Transcript of How (not) to document
// // Dear maintainer: // // Once you are done trying to 'optimize' this routine, // and have realized what a terrible mistake that was, // please increment the following counter as a warning // to the next guy: // // total_hours_wasted_here = 42 //
Janos Pasztor
Development Lead @
Sole Proprietor @
Who am I?
DistribLoad subscription management system
IxoPay payment services
IxoAds marketing and advertisements
Customer support services
We are hiring: ixolit.com/careers
Work with us!
IT consulting
Linux-based web stacks
Performance problems
Infrastructure cleanup
Open source projects
Educational videos
That’s
me!
Where?
What?
Who?How?
When?
DocumentationDocumentationWhy?
When?
When?
Stop feeling badabout it!
Business value!
When?
Why?
Why?
Preserve information
Why?
Preserve informationfor others
Why?
Preserve informationfor ourselves
Why?
Prepare for meetings
Why?
Preserve decisions
Why?
Teach the new employee
Why?
Teach the customer
How?
How?
How?
How?
Make it sexy!
How? Focus attention
How? Focus attention
How? Fill the frame
How? Example
How?
Structure your content!
How? Structure
How? Structure
How?
Watch your language!
How? Language
How?
“This class show upthe bill”
Language
How?
“This class createsthe invoice”
Language
Where?
Where?
Wiki software
“…a Wiki is where gooddocumentation goes to die.”
— Jacob Kaplan-MossPyCon US 2014
Where? Wiki software
Where? Wiki software
Where? Wiki software
Where? Wiki software
Where? Wiki software
Where? Wiki software
Where? Wiki software
Dokuwiki
Where? Wiki software
Where? Wiki software
Where? Wiki software
Where?
Documentation generators
Where? Generators
Where? Generators
Where?
Interactive documentation
Where? Interactive
Where? Interactive
Where? Interactive
Where? Interactive
Where? Interactive
Where? Interactive
Twilio
What?
What?
Business decisions
What?
What happened when?
Business decisions
What?
January 1, 2012: VAT changes to 27%
Business decisions
What?
Date X:We change our
signup flow
Business decisions
What? Business decisions
What?
Projects
What?
Project overview
Projects
What? Projects
What? Projects
What?
Non-trivialbusiness cases
Projects
What?
Big modules
Projects
What?
Class/code docs
Projects
What?
Provide examples!
Projects
What?
Document the WHYnot the WHAT!
Projects
Who?
Who?
Everyone! (DUH)
Who?
Dream on…
Who?
The new guy?girl
Who?
The person whoknows the most!
Who?
Copy-paste
Who?
Keeping itup to date
Summary
Summary
1. Business-critical first2. Easy to edit3. Good structures4. Up to date
Thank you
Thank you for listening!
