The Documentation
Developer’s Torment
Zbyszko Papierski
#dynatrace @zpapierski
Jakub Marchwicki
@kubem #casumo
Slide 2
Slide 2 text
No content
Slide 3
Slide 3 text
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)
Software engineer
Chief Mob Officer
Jakub Marchwicki <@kubem>
http://jakub.marchwicki.pl
Slide 13
Slide 13 text
Sales pitch for everyone!!
Slide 14
Slide 14 text
“Who has the knowledge?”
Slide 15
Slide 15 text
No content
Slide 16
Slide 16 text
Who needs documentation, anyway?
Slide 17
Slide 17 text
Are we solving the right problem?
Slide 18
Slide 18 text
Solving problems with the documentation when
documentation is not the answer
Slide 19
Slide 19 text
We document a thing
where nobody will be looking for it
Slide 20
Slide 20 text
What to document?
Business and domain
High level architecture
Low
level design
Slide 21
Slide 21 text
what
distinguish
is documented
how
to document it
from
Slide 22
Slide 22 text
Business and domain
High level architecture
Low level design
Slide 23
Slide 23 text
Decision Sustainability Piramid (DSP ™)
Business and domain
High level architecture
Low level design
Slide 24
Slide 24 text
Decision Sustainability Piramid (DSP ™)
Business and domain
High level architecture
Low level design
patent pending
Slide 25
Slide 25 text
What to document?
Business and domain
High level architecture
Low
level design
Slide 26
Slide 26 text
a flexible workshop format for
collaborative exploration of complex
business domains,
beyond silo and specialisation boundaries.
Slide 27
Slide 27 text
EventStorming
a flexible workshop format for
collaborative exploration of complex
business domains,
beyond silo and specialisation boundaries.
Slide 28
Slide 28 text
No content
Slide 29
Slide 29 text
No content
Slide 30
Slide 30 text
No content
Slide 31
Slide 31 text
No content
Slide 32
Slide 32 text
No content
Slide 33
Slide 33 text
No content
Slide 34
Slide 34 text
No content
Slide 35
Slide 35 text
No content
Slide 36
Slide 36 text
No content
Slide 37
Slide 37 text
No content
Slide 38
Slide 38 text
No content
Slide 39
Slide 39 text
No content
Slide 40
Slide 40 text
No content
Slide 41
Slide 41 text
No content
Slide 42
Slide 42 text
No content
Slide 43
Slide 43 text
Product is:
● Item in sales pitch
● Inventory Element in API
● Inventory Element, Item and Product in the code
Slide 44
Slide 44 text
Why does it matter?
Slide 45
Slide 45 text
No content
Slide 46
Slide 46 text
No content
Slide 47
Slide 47 text
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
Slide 48
Slide 48 text
Ubiquitous language
Slide 49
Slide 49 text
No content
Slide 50
Slide 50 text
What to document?
Business and domain
High level architecture
Low
level design
Slide 51
Slide 51 text
What is your architecture?
Slide 52
Slide 52 text
What is your architecture?
How do you solve your business goals with
technology?
Slide 53
Slide 53 text
How vs Why
Slide 54
Slide 54 text
but document
Let the architecture emerge
what has emerged!
Slide 55
Slide 55 text
Architecture is decisions
Slide 56
Slide 56 text
Architecture Decision Record
Slide 57
Slide 57 text
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/
Slide 58
Slide 58 text
D
A
C
I
Slide 59
Slide 59 text
Driver
A
C
I
Slide 60
Slide 60 text
Driver
Approver
C
I
Slide 61
Slide 61 text
Driver
Approver
Contributors
I
Slide 62
Slide 62 text
Driver
Approver
Contributors
Informed
Slide 63
Slide 63 text
No content
Slide 64
Slide 64 text
What to document?
Business and domain
High level architecture
Low
level design
Slide 65
Slide 65 text
Main villains
Slide 66
Slide 66 text
Villain nr 1 - outdated wiki pages
Slide 67
Slide 67 text
Villain nr 2 - tribal knowledge
Slide 68
Slide 68 text
Villain nr 3 - confusing design
Slide 69
Slide 69 text
Code design documentation? Sure, but...
Slide 70
Slide 70 text
API Code design documentation? Sure, but...
Slide 71
Slide 71 text
Discoverability is better
https://blog.jooq.org/2013/11/22/using-jooq-with-groovy/
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
Slide 82
Slide 82 text
The User Experience of
documentation
Slide 83
Slide 83 text
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/
Slide 84
Slide 84 text
● 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?
Slide 85
Slide 85 text
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?
Slide 86
Slide 86 text
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?
Slide 87
Slide 87 text
● 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?
Slide 88
Slide 88 text
Thank you!
Zbyszko Papierski
#dynatrace @zpapierski
Jakub Marchwicki
@kubem #casumo