Developers Torment: The Documentation

You start a new job. You’re excited - new domain, new knowledge to ingest, new practices to learn. Unfortunately, once you start digging into things, excitement starts to fade and is replaced by frustration. It turns out that there is no way to find out about the product unless you somehow get a hold of sales pitch presentation. You can only learn about architecture if you talk to “that guy” and only if he’ll have 3 hours to spare (spoiler alert: he won’t). In short - tribal knowledge is the only way to go. It’s actually not the worst case scenario. Instead of missing documentation, more often than not you’ll stumble upon one that is simply out of date. Described build process always fails? Your fault, why wouldn’t you know about that one file with dependencies version you have to create manually after pulling the repo? Docs say we use Cassandra to store our data? Well, we did - in 2010. There is a different side to this - in some projects, on the other hand, you feel like the only thing you do is writing the docs. Many of those are probably out of date right now. Others, while helpful, will probably just be lost among the ones not helpful at all. How do you enjoy the fact that you’re creating a document that nobody will ever read? Is there no way out of this hell? Does onboarding process have to be the rite of passage, where your enthusiasm is crushed by the heavy weight of hopelessness? How to write and maintain documentation in the way, that it is an actual advantage to you and yours, and not a pile of shame? During our talk, we’ll analyze what are the actual issues with the docs, do we actually need it and how to go with quality, not quantity. Don’t worry, we won’t leave you without the tools to tackle this beast.

Transcript

1. The Documentation Developer’s Torment Zbyszko Papierski #dynatrace @zpapierski Jakub Marchwicki @kubem #casumo
3. TL;DR documentation must be Just In Time appear promptly (right time) in a places we expect (right place) giving us information we need (right context)
6. 2 = 1 + 1
8. public interface Stream<T> { <R> Stream<R> map(Function<? super T, ? extends R> mapper); <R> Stream<R> flatMap(Function<? super T, ? extends Stream<? extends R>> mapper); }
9. public interface Stream<T> { <R> Stream<R> map(Function<? super T, ? extends R> mapper); <R> Stream<R> flatMap(Function<? super T, ? extends Stream<? extends R>> mapper); } public interface Optional<T> { <U> Optional<U> map(Function<? super T, ? extends U> mapper); <U> Optional<U> flatMap(Function<? super T, ? extends Optional<? extends U>> mapper); }
10. public interface Stream<T> { <R> Stream<R> map(Function<? super T, ? extends R> mapper); <R> Stream<R> flatMap(Function<? super T, ? extends Stream<? extends R>> mapper); } public interface Optional<T> { <U> Optional<U> map(Function<? super T, ? extends U> mapper); <U> Optional<U> flatMap(Function<? super T, ? extends Optional<? extends U>> mapper); } public interface CompletionStage<T> { <U> CompletionStage<U> … (Function<? super T, ? extends U> fn); <U> CompletionStage<U> … (Function<? super T, ? extends CompletionStage<? extends U>> fn); } thenApply thenCompose
11. Software engineer Organizer Zbyszko Papierski <@zpapierski> He’s somewhere there, look!
12. Software engineer Chief Mob Officer Jakub Marchwicki <@kubem> http://jakub.marchwicki.pl
13. Sales pitch for everyone!!
14. “Who has the knowledge?”
16. Who needs documentation, anyway?
17. Are we solving the right problem?
18. Solving problems with the documentation when documentation is not the answer
19. We document a thing where nobody will be looking for it
20. What to document? Business and domain High level architecture Low level design
21. what distinguish is documented how to document it from
22. Business and domain High level architecture Low level design
23. Decision Sustainability Piramid (DSP ™) Business and domain High level architecture Low level design
24. Decision Sustainability Piramid (DSP ™) Business and domain High level architecture Low level design patent pending
25. What to document? Business and domain High level architecture Low level design
26. a flexible workshop format for collaborative exploration of complex business domains, beyond silo and specialisation boundaries.
27. EventStorming a flexible workshop format for collaborative exploration of complex business domains, beyond silo and specialisation boundaries.
43. Product is: • Item in sales pitch • Inventory Element in API • Inventory Element, Item and Product in the code
44. Why does it matter?
47. My library add series add an episode paid/not paid labels run time: 1h 35 min dr Home season 1 episode 29 What PO said What devs understood movies list add category add flv file status [checkbox] tag cloud length: 2 100 000 ms 8fga324jfdsh.flv from: Michał Bartyzel - Oprogramowanie szyte na miare
48. Ubiquitous language
50. What to document? Business and domain High level architecture Low level design
51. What is your architecture?
52. What is your architecture? How do you solve your business goals with technology?
53. How vs Why
54. but document Let the architecture emerge what has emerged!
55. Architecture is decisions
56. Architecture Decision Record
57. Example: Data Abstraction Model • Context: (...) there needs to be a way for modules to "speak a common language" for data manipulation and persistence. • Decision: provide a lightweight model for data abstraction and persistence, oriented around the Entity/Attribute mode • Status: ACCEPTED • Consequences: ◦ Users and modules can define the shape and structure of their domain data in a way that is independent of any particular database or type of database. ◦ Modules can perform basic data persistence tasks in a database-agnostic way. https://github.com/arachne-framework/architecture/
58. D A C I
59. Driver A C I
60. Driver Approver C I
61. Driver Approver Contributors I
62. Driver Approver Contributors Informed
64. What to document? Business and domain High level architecture Low level design
65. Main villains
66. Villain nr 1 - outdated wiki pages
67. Villain nr 2 - tribal knowledge
68. Villain nr 3 - confusing design
69. Code design documentation? Sure, but...
70. API Code design documentation? Sure, but...
71. Discoverability is better https://blog.jooq.org/2013/11/22/using-jooq-with-groovy/
72. Recall vs Recognition
73. Strongly Typed
74. Stringly Strongly Typed
75. String#regionMatches(int, String, int, int) String#regionMatches(boolean, int, String, int, int)
76. Simplicity is better
77. Simplicity is better It is far more difficult to be simple than to be complicated John Ruskin
78. Consistency is better
79. public interface Stream<T> { <R> Stream<R> map(Function<? super T, ? extends R> mapper); <R> Stream<R> flatMap(Function<? super T, ? extends Stream<? extends R>> mapper); } public interface Optional<T> { <U> Optional<U> map(Function<? super T, ? extends U> mapper); <U> Optional<U> flatMap(Function<? super T, ? extends Optional<? extends U>> mapper); } public interface CompletionStage<T> { <U> CompletionStage<U> thenCompose (Function<? super T, ? extends U> fn); <U> CompletionStage<U> thenApply (Function<? super T, ? extends CompletionStage<? extends U>> fn); }
80. Consistency is the king!
81. Consistency is the king! If you work for acme on a service called registration then • Repository: http://gilab.com/acme/registration • Production deployment: http://registration.acme.cloud:8080 • Swagger http://registration.acme.cloud:8080/v2/api-docs • Traces: http://zipkin.acme.cloud/zipkin/?serviceName=registration • Metrics: http://grafana.acme.cloud/dashboard/db/registration • The README.adoc contains a section Context which describes the purpose of the service. • Derive upstream services from traces or circuit breakers activity
82. The User Experience of documentation
83. Usability 101 • Learnability: How easy is it for users to accomplish basic tasks the first time after reading the documentation? • Efficiency: Once users have learned the design, how quickly can they perform tasks? • Memorability: When users want to return to the documentation after a period of not using it, how easy they can find it? • Errors: How many errors do users make, how severe are these errors, and how easily can they recover from the errors? • Satisfaction: How pleasant is it to use the documentation? Is it adequate? Up-to-date? https://www.nngroup.com/articles/usability-101-introduction-to-usability/
84. • Learnability: How easy is it for users to accomplish basic tasks the first time after reading the documentation? • Efficiency: Once users have learned the design, how quickly can they perform tasks? • Memorability: When users want to return to the documentation after a period of not using it, how easy they can find it? • Errors: How many errors do users make, how severe are these errors, and how easily can they recover from the errors? • Satisfaction: How pleasant is it to use the documentation? Is it adequate? Up-to-date? is it LEMES?
85. LEMES of business and domain • Learnability: How easy is it for users to accomplish basic tasks the first time after reading the documentation? • Efficiency: Once users have learned the design, how quickly can they perform tasks? • Memorability: When users want to return to the documentation after a period of not using it, how easy they can find it? • Errors: How many errors do users make, how severe are these errors, and how easily can they recover from the errors? • Satisfaction: How pleasant is it to use the documentation? Is it adequate? Up-to-date?
86. LEMES of decisions and records • Learnability: How easy is it for users to accomplish basic tasks the first time after reading the documentation? • Efficiency: Once users have learned the design, how quickly can they perform tasks? • Memorability: When users want to return to the documentation after a period of not using it, how easy they can find it? • Errors: How many errors do users make, how severe are these errors, and how easily can they recover from the errors? • Satisfaction: How pleasant is it to use the documentation? Is it adequate? Up-to-date?
87. • Learnability: How easy is it for users to accomplish basic tasks the first time after reading the documentation? • Efficiency: Once users have learned the design, how quickly can they perform tasks? • Memorability: When users want to return to the documentation after a period of not using it, how easy they can find it? • Errors: How many errors do users make, how severe are these errors, and how easily can they recover from the errors? • Satisfaction: How pleasant is it to use the documentation? Is it adequate? Up-to-date? is it LEMES?
88. Thank you! Zbyszko Papierski #dynatrace @zpapierski Jakub Marchwicki @kubem #casumo
89. Developer’s Torment :: The Documentation :: Links • EventStorming ◦ Links + timelapse: https://github.com/mariuszgil/awesome-eventstorming ◦ Site: https://www.eventstorming.com/ ◦ Book: https://leanpub.com/introducing_eventstorming • Architecture Decision Records ◦ http://thinkrelevance.com/blog/2011/11/15/documenting-architecture-decisions ◦ Project example: https://github.com/arachne-framework/architecture/ ◦ Tolling: https://adr.github.io/ and https://github.com/npryce/adr-tools/ • DACI ◦ https://bit.ly/2PpHos Zbyszko Papierski #dynatrace @zpapierski Jakub Marchwicki @kubem #casumo