how (not) to document
TRANSCRIPT
![Page 1: How (not) to document](https://reader034.vdocuments.site/reader034/viewer/2022052514/5a65a4cd7f8b9a38648b4899/html5/thumbnails/1.jpg)
// // 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 //
![Page 2: How (not) to document](https://reader034.vdocuments.site/reader034/viewer/2022052514/5a65a4cd7f8b9a38648b4899/html5/thumbnails/2.jpg)
Janos Pasztor
Development Lead @
Sole Proprietor @
Who am I?
![Page 3: How (not) to document](https://reader034.vdocuments.site/reader034/viewer/2022052514/5a65a4cd7f8b9a38648b4899/html5/thumbnails/3.jpg)
DistribLoad subscription management system
IxoPay payment services
IxoAds marketing and advertisements
Customer support services
We are hiring: ixolit.com/careers
Work with us!
![Page 4: How (not) to document](https://reader034.vdocuments.site/reader034/viewer/2022052514/5a65a4cd7f8b9a38648b4899/html5/thumbnails/4.jpg)
IT consulting
Linux-based web stacks
Performance problems
Infrastructure cleanup
Open source projects
Educational videos
That’s
me!
![Page 5: How (not) to document](https://reader034.vdocuments.site/reader034/viewer/2022052514/5a65a4cd7f8b9a38648b4899/html5/thumbnails/5.jpg)
Where?
What?
Who?How?
When?
DocumentationDocumentationWhy?
![Page 6: How (not) to document](https://reader034.vdocuments.site/reader034/viewer/2022052514/5a65a4cd7f8b9a38648b4899/html5/thumbnails/6.jpg)
When?
![Page 7: How (not) to document](https://reader034.vdocuments.site/reader034/viewer/2022052514/5a65a4cd7f8b9a38648b4899/html5/thumbnails/7.jpg)
When?
Stop feeling badabout it!
![Page 8: How (not) to document](https://reader034.vdocuments.site/reader034/viewer/2022052514/5a65a4cd7f8b9a38648b4899/html5/thumbnails/8.jpg)
Business value!
When?
![Page 9: How (not) to document](https://reader034.vdocuments.site/reader034/viewer/2022052514/5a65a4cd7f8b9a38648b4899/html5/thumbnails/9.jpg)
Why?
![Page 10: How (not) to document](https://reader034.vdocuments.site/reader034/viewer/2022052514/5a65a4cd7f8b9a38648b4899/html5/thumbnails/10.jpg)
Why?
Preserve information
![Page 11: How (not) to document](https://reader034.vdocuments.site/reader034/viewer/2022052514/5a65a4cd7f8b9a38648b4899/html5/thumbnails/11.jpg)
Why?
Preserve informationfor others
![Page 12: How (not) to document](https://reader034.vdocuments.site/reader034/viewer/2022052514/5a65a4cd7f8b9a38648b4899/html5/thumbnails/12.jpg)
Why?
Preserve informationfor ourselves
![Page 13: How (not) to document](https://reader034.vdocuments.site/reader034/viewer/2022052514/5a65a4cd7f8b9a38648b4899/html5/thumbnails/13.jpg)
Why?
Prepare for meetings
![Page 14: How (not) to document](https://reader034.vdocuments.site/reader034/viewer/2022052514/5a65a4cd7f8b9a38648b4899/html5/thumbnails/14.jpg)
Why?
Preserve decisions
![Page 15: How (not) to document](https://reader034.vdocuments.site/reader034/viewer/2022052514/5a65a4cd7f8b9a38648b4899/html5/thumbnails/15.jpg)
Why?
Teach the new employee
![Page 16: How (not) to document](https://reader034.vdocuments.site/reader034/viewer/2022052514/5a65a4cd7f8b9a38648b4899/html5/thumbnails/16.jpg)
Why?
Teach the customer
![Page 17: How (not) to document](https://reader034.vdocuments.site/reader034/viewer/2022052514/5a65a4cd7f8b9a38648b4899/html5/thumbnails/17.jpg)
How?
![Page 18: How (not) to document](https://reader034.vdocuments.site/reader034/viewer/2022052514/5a65a4cd7f8b9a38648b4899/html5/thumbnails/18.jpg)
How?
![Page 19: How (not) to document](https://reader034.vdocuments.site/reader034/viewer/2022052514/5a65a4cd7f8b9a38648b4899/html5/thumbnails/19.jpg)
How?
![Page 20: How (not) to document](https://reader034.vdocuments.site/reader034/viewer/2022052514/5a65a4cd7f8b9a38648b4899/html5/thumbnails/20.jpg)
How?
Make it sexy!
![Page 21: How (not) to document](https://reader034.vdocuments.site/reader034/viewer/2022052514/5a65a4cd7f8b9a38648b4899/html5/thumbnails/21.jpg)
How? Focus attention
![Page 22: How (not) to document](https://reader034.vdocuments.site/reader034/viewer/2022052514/5a65a4cd7f8b9a38648b4899/html5/thumbnails/22.jpg)
How? Focus attention
![Page 23: How (not) to document](https://reader034.vdocuments.site/reader034/viewer/2022052514/5a65a4cd7f8b9a38648b4899/html5/thumbnails/23.jpg)
How? Fill the frame
![Page 25: How (not) to document](https://reader034.vdocuments.site/reader034/viewer/2022052514/5a65a4cd7f8b9a38648b4899/html5/thumbnails/25.jpg)
How? Example
![Page 26: How (not) to document](https://reader034.vdocuments.site/reader034/viewer/2022052514/5a65a4cd7f8b9a38648b4899/html5/thumbnails/26.jpg)
How?
Structure your content!
![Page 27: How (not) to document](https://reader034.vdocuments.site/reader034/viewer/2022052514/5a65a4cd7f8b9a38648b4899/html5/thumbnails/27.jpg)
How? Structure
![Page 28: How (not) to document](https://reader034.vdocuments.site/reader034/viewer/2022052514/5a65a4cd7f8b9a38648b4899/html5/thumbnails/28.jpg)
How? Structure
![Page 29: How (not) to document](https://reader034.vdocuments.site/reader034/viewer/2022052514/5a65a4cd7f8b9a38648b4899/html5/thumbnails/29.jpg)
How?
Watch your language!
![Page 30: How (not) to document](https://reader034.vdocuments.site/reader034/viewer/2022052514/5a65a4cd7f8b9a38648b4899/html5/thumbnails/30.jpg)
How? Language
![Page 31: How (not) to document](https://reader034.vdocuments.site/reader034/viewer/2022052514/5a65a4cd7f8b9a38648b4899/html5/thumbnails/31.jpg)
How?
“This class show upthe bill”
Language
![Page 32: How (not) to document](https://reader034.vdocuments.site/reader034/viewer/2022052514/5a65a4cd7f8b9a38648b4899/html5/thumbnails/32.jpg)
How?
“This class createsthe invoice”
Language
![Page 33: How (not) to document](https://reader034.vdocuments.site/reader034/viewer/2022052514/5a65a4cd7f8b9a38648b4899/html5/thumbnails/33.jpg)
Where?
![Page 34: How (not) to document](https://reader034.vdocuments.site/reader034/viewer/2022052514/5a65a4cd7f8b9a38648b4899/html5/thumbnails/34.jpg)
Where?
Wiki software
![Page 35: How (not) to document](https://reader034.vdocuments.site/reader034/viewer/2022052514/5a65a4cd7f8b9a38648b4899/html5/thumbnails/35.jpg)
“…a Wiki is where gooddocumentation goes to die.”
— Jacob Kaplan-MossPyCon US 2014
Where? Wiki software
![Page 36: How (not) to document](https://reader034.vdocuments.site/reader034/viewer/2022052514/5a65a4cd7f8b9a38648b4899/html5/thumbnails/36.jpg)
Where? Wiki software
![Page 37: How (not) to document](https://reader034.vdocuments.site/reader034/viewer/2022052514/5a65a4cd7f8b9a38648b4899/html5/thumbnails/37.jpg)
Where? Wiki software
![Page 38: How (not) to document](https://reader034.vdocuments.site/reader034/viewer/2022052514/5a65a4cd7f8b9a38648b4899/html5/thumbnails/38.jpg)
Where? Wiki software
![Page 39: How (not) to document](https://reader034.vdocuments.site/reader034/viewer/2022052514/5a65a4cd7f8b9a38648b4899/html5/thumbnails/39.jpg)
Where? Wiki software
![Page 40: How (not) to document](https://reader034.vdocuments.site/reader034/viewer/2022052514/5a65a4cd7f8b9a38648b4899/html5/thumbnails/40.jpg)
Where? Wiki software
![Page 41: How (not) to document](https://reader034.vdocuments.site/reader034/viewer/2022052514/5a65a4cd7f8b9a38648b4899/html5/thumbnails/41.jpg)
Where? Wiki software
Dokuwiki
![Page 42: How (not) to document](https://reader034.vdocuments.site/reader034/viewer/2022052514/5a65a4cd7f8b9a38648b4899/html5/thumbnails/42.jpg)
Where? Wiki software
![Page 43: How (not) to document](https://reader034.vdocuments.site/reader034/viewer/2022052514/5a65a4cd7f8b9a38648b4899/html5/thumbnails/43.jpg)
Where? Wiki software
![Page 44: How (not) to document](https://reader034.vdocuments.site/reader034/viewer/2022052514/5a65a4cd7f8b9a38648b4899/html5/thumbnails/44.jpg)
Where? Wiki software
![Page 45: How (not) to document](https://reader034.vdocuments.site/reader034/viewer/2022052514/5a65a4cd7f8b9a38648b4899/html5/thumbnails/45.jpg)
Where?
Documentation generators
![Page 46: How (not) to document](https://reader034.vdocuments.site/reader034/viewer/2022052514/5a65a4cd7f8b9a38648b4899/html5/thumbnails/46.jpg)
Where? Generators
![Page 47: How (not) to document](https://reader034.vdocuments.site/reader034/viewer/2022052514/5a65a4cd7f8b9a38648b4899/html5/thumbnails/47.jpg)
Where? Generators
![Page 48: How (not) to document](https://reader034.vdocuments.site/reader034/viewer/2022052514/5a65a4cd7f8b9a38648b4899/html5/thumbnails/48.jpg)
Where?
Interactive documentation
![Page 49: How (not) to document](https://reader034.vdocuments.site/reader034/viewer/2022052514/5a65a4cd7f8b9a38648b4899/html5/thumbnails/49.jpg)
Where? Interactive
![Page 50: How (not) to document](https://reader034.vdocuments.site/reader034/viewer/2022052514/5a65a4cd7f8b9a38648b4899/html5/thumbnails/50.jpg)
Where? Interactive
![Page 51: How (not) to document](https://reader034.vdocuments.site/reader034/viewer/2022052514/5a65a4cd7f8b9a38648b4899/html5/thumbnails/51.jpg)
Where? Interactive
![Page 52: How (not) to document](https://reader034.vdocuments.site/reader034/viewer/2022052514/5a65a4cd7f8b9a38648b4899/html5/thumbnails/52.jpg)
Where? Interactive
![Page 53: How (not) to document](https://reader034.vdocuments.site/reader034/viewer/2022052514/5a65a4cd7f8b9a38648b4899/html5/thumbnails/53.jpg)
Where? Interactive
![Page 54: How (not) to document](https://reader034.vdocuments.site/reader034/viewer/2022052514/5a65a4cd7f8b9a38648b4899/html5/thumbnails/54.jpg)
Where? Interactive
Twilio
![Page 55: How (not) to document](https://reader034.vdocuments.site/reader034/viewer/2022052514/5a65a4cd7f8b9a38648b4899/html5/thumbnails/55.jpg)
What?
![Page 56: How (not) to document](https://reader034.vdocuments.site/reader034/viewer/2022052514/5a65a4cd7f8b9a38648b4899/html5/thumbnails/56.jpg)
What?
Business decisions
![Page 57: How (not) to document](https://reader034.vdocuments.site/reader034/viewer/2022052514/5a65a4cd7f8b9a38648b4899/html5/thumbnails/57.jpg)
What?
What happened when?
Business decisions
![Page 58: How (not) to document](https://reader034.vdocuments.site/reader034/viewer/2022052514/5a65a4cd7f8b9a38648b4899/html5/thumbnails/58.jpg)
What?
January 1, 2012: VAT changes to 27%
Business decisions
![Page 59: How (not) to document](https://reader034.vdocuments.site/reader034/viewer/2022052514/5a65a4cd7f8b9a38648b4899/html5/thumbnails/59.jpg)
What?
Date X:We change our
signup flow
Business decisions
![Page 60: How (not) to document](https://reader034.vdocuments.site/reader034/viewer/2022052514/5a65a4cd7f8b9a38648b4899/html5/thumbnails/60.jpg)
What? Business decisions
![Page 61: How (not) to document](https://reader034.vdocuments.site/reader034/viewer/2022052514/5a65a4cd7f8b9a38648b4899/html5/thumbnails/61.jpg)
What?
Projects
![Page 62: How (not) to document](https://reader034.vdocuments.site/reader034/viewer/2022052514/5a65a4cd7f8b9a38648b4899/html5/thumbnails/62.jpg)
What?
Project overview
Projects
![Page 63: How (not) to document](https://reader034.vdocuments.site/reader034/viewer/2022052514/5a65a4cd7f8b9a38648b4899/html5/thumbnails/63.jpg)
What? Projects
![Page 64: How (not) to document](https://reader034.vdocuments.site/reader034/viewer/2022052514/5a65a4cd7f8b9a38648b4899/html5/thumbnails/64.jpg)
What? Projects
![Page 65: How (not) to document](https://reader034.vdocuments.site/reader034/viewer/2022052514/5a65a4cd7f8b9a38648b4899/html5/thumbnails/65.jpg)
What?
Non-trivialbusiness cases
Projects
![Page 66: How (not) to document](https://reader034.vdocuments.site/reader034/viewer/2022052514/5a65a4cd7f8b9a38648b4899/html5/thumbnails/66.jpg)
What?
Big modules
Projects
![Page 67: How (not) to document](https://reader034.vdocuments.site/reader034/viewer/2022052514/5a65a4cd7f8b9a38648b4899/html5/thumbnails/67.jpg)
What?
Class/code docs
Projects
![Page 68: How (not) to document](https://reader034.vdocuments.site/reader034/viewer/2022052514/5a65a4cd7f8b9a38648b4899/html5/thumbnails/68.jpg)
What?
Provide examples!
Projects
![Page 69: How (not) to document](https://reader034.vdocuments.site/reader034/viewer/2022052514/5a65a4cd7f8b9a38648b4899/html5/thumbnails/69.jpg)
What?
Document the WHYnot the WHAT!
Projects
![Page 70: How (not) to document](https://reader034.vdocuments.site/reader034/viewer/2022052514/5a65a4cd7f8b9a38648b4899/html5/thumbnails/70.jpg)
Who?
![Page 71: How (not) to document](https://reader034.vdocuments.site/reader034/viewer/2022052514/5a65a4cd7f8b9a38648b4899/html5/thumbnails/71.jpg)
Who?
Everyone! (DUH)
![Page 72: How (not) to document](https://reader034.vdocuments.site/reader034/viewer/2022052514/5a65a4cd7f8b9a38648b4899/html5/thumbnails/72.jpg)
Who?
Dream on…
![Page 73: How (not) to document](https://reader034.vdocuments.site/reader034/viewer/2022052514/5a65a4cd7f8b9a38648b4899/html5/thumbnails/73.jpg)
Who?
The new guy?girl
![Page 74: How (not) to document](https://reader034.vdocuments.site/reader034/viewer/2022052514/5a65a4cd7f8b9a38648b4899/html5/thumbnails/74.jpg)
Who?
The person whoknows the most!
![Page 75: How (not) to document](https://reader034.vdocuments.site/reader034/viewer/2022052514/5a65a4cd7f8b9a38648b4899/html5/thumbnails/75.jpg)
Who?
Copy-paste
![Page 76: How (not) to document](https://reader034.vdocuments.site/reader034/viewer/2022052514/5a65a4cd7f8b9a38648b4899/html5/thumbnails/76.jpg)
Who?
Keeping itup to date
![Page 77: How (not) to document](https://reader034.vdocuments.site/reader034/viewer/2022052514/5a65a4cd7f8b9a38648b4899/html5/thumbnails/77.jpg)
Summary
![Page 78: How (not) to document](https://reader034.vdocuments.site/reader034/viewer/2022052514/5a65a4cd7f8b9a38648b4899/html5/thumbnails/78.jpg)
Summary
1. Business-critical first2. Easy to edit3. Good structures4. Up to date
![Page 79: How (not) to document](https://reader034.vdocuments.site/reader034/viewer/2022052514/5a65a4cd7f8b9a38648b4899/html5/thumbnails/79.jpg)
Thank you
Thank you for listening!