How (not) to document
0 likes445 views
The document discusses the importance of proper documentation in a business context, highlighting the value of preserving information for future reference and training. It touches on issues related to infrastructure, performance problems, and the need for clear communication in documentation practices. The author emphasizes the importance of creating easily editable and well-structured documents that remain up to date.
How (not) to document
- 1. // // 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 //
- 2. Janos Pasztor Development Lead @ Sole Proprietor @ Who am I?
- 3. DistribLoad subscription management system IxoPay payment services IxoAds marketing and advertisements Customer support services We are hiring: ixolit.com/careers Work with us!
- 4. IT consulting Linux-based web stacks Performance problems Infrastructure cleanup Open source projects Educational videos That’sm e!
- 6. When?
- 7. When? Stop feeling bad about it!
- 9. Why?
- 17. How?
- 18. How?
- 19. How?
- 23. How? Fill the frame
- 25. How? Example
- 27. How? Structure
- 28. How? Structure
- 30. How? Language
- 31. How? “This class show up the bill” Language
- 32. How? “This class creates the invoice” Language
- 33. Where?
- 35. “…a Wiki is where good documentation goes to die.” — Jacob Kaplan-Moss PyCon US 2014 Where? Wiki software
- 55. What?
- 57. What? What happened when? Business decisions
- 58. What? January 1, 2012: VAT changes to 27% Business decisions
- 59. What? Date X: We change our signup flow Business decisions
- 61. What? Projects
- 63. What? Projects
- 64. What? Projects
- 69. What? Document the WHY not the WHAT! Projects
- 70. Who?
- 72. Who? Dream on…
- 74. Who? The person who knows the most!
- 75. Who? Copy-paste
- 76. Who? Keeping it up to date
- 77. Summary
- 78. Summary 1. Business-critical first 2. Easy to edit 3. Good structures 4. Up to date
- 79. Thank you Thank you for listening!