nos Pásztor: How (not) to document Let’s face it: writing documentation is fundamentally boring. Unless you’re a total graphomaniac, chances are you are not writing as much documentation as you should be, or if you do, you find it hard to organize it in a useful manner. Grab a cup of coffee and join me on a journey of the good, the bad and the ugly parts of writing documentation. By the time we are finished, you will find writing and reading documentation a lot easier.

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!

5. Where?
What?
Who?How?
When?
DocumentationDocumentationWhy?

6. When?

7. When?
Stop feeling bad
about it!

8. Business value!
When?

9. Why?

10. Why?
Preserve information

11. Why?
Preserve information
for others

12. Why?
Preserve information
for ourselves

13. Why?
Prepare for meetings

14. Why?
Preserve decisions

15. Why?
Teach the new
employee

16. Why?
Teach the customer

17. How?

18. How?

19. How?

20. How?
Make it sexy!

21. How? Focus attention

22. How? Focus attention

23. How? Fill the frame

24. How? Typography
getbootstrap.com

25. How? Example

26. How?
Structure your
content!

27. How? Structure

28. How? Structure

29. How?
Watch your language!

30. How? Language

31. How?
“This class show up
the bill”
Language

32. How?
“This class creates
the invoice”
Language

33. Where?

34. Where?
Wiki software

35. “…a Wiki is where good
documentation goes to die.”
— Jacob Kaplan-Moss
PyCon US 2014
Where? Wiki software

36. Where? Wiki software

37. Where? Wiki software

38. Where? Wiki software

39. Where? Wiki software

40. Where? Wiki software

41. Where? Wiki software
Dokuwiki

42. Where? Wiki software

43. Where? Wiki software

44. Where? Wiki software

45. Where?
Documentation
generators

46. Where? Generators

47. Where? Generators

48. Where?
Interactive
documentation

49. Where? Interactive

50. Where? Interactive

51. Where? Interactive

52. Where? Interactive

53. Where? Interactive

54. Where? Interactive
Twilio

55. What?

56. What?
Business decisions

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

60. What? Business decisions

61. What?
Projects

62. What?
Project overview
Projects

63. What? Projects

64. What? Projects

65. What?
Non-trivial
business cases
Projects

66. What?
Big modules
Projects

67. What?
Class/code docs
Projects

68. What?
Provide examples!
Projects

69. What?
Document the WHY
not the WHAT!
Projects

70. Who?

71. Who?
Everyone! (DUH)

72. Who?
Dream on…

73. Who?
The new guy?
girl

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!