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
   

   View Slide

2. View Slide

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)
   

   View Slide

4. View Slide

5. View Slide

6. 2 = 1 + 1
   

   View Slide

7. View Slide

8. public interface Stream {
   Stream map(Function super T, ? extends R> mapper);
   Stream flatMap(Function super T, ? extends Stream extends R>> mapper);
   }
   

   View Slide

9. public interface Stream {
   Stream map(Function super T, ? extends R> mapper);
   Stream flatMap(Function super T, ? extends Stream extends R>> mapper);
   }
   public interface Optional {
   Optional map(Function super T, ? extends U> mapper);
   Optional flatMap(Function super T, ? extends Optional extends U>> mapper);
   }
   

   View Slide

10. public interface Stream {
    Stream map(Function super T, ? extends R> mapper);
    Stream flatMap(Function super T, ? extends Stream extends R>> mapper);
    }
    public interface Optional {
    Optional map(Function super T, ? extends U> mapper);
    Optional flatMap(Function super T, ? extends Optional extends U>> mapper);
    }
    public interface CompletionStage {
    CompletionStage … (Function super T, ? extends U> fn);
    CompletionStage … (Function super T, ? extends CompletionStage extends U>> fn);
    }
    thenApply
    thenCompose
    

    View Slide

11. Software engineer
    Organizer
    Zbyszko Papierski
    <@zpapierski>
    He’s somewhere there, look!
    

    View Slide

12. Software engineer
    Chief Mob Officer
    Jakub Marchwicki <@kubem>
    http://jakub.marchwicki.pl
    

    View Slide

13. Sales pitch for everyone!!
    

    View Slide

14. “Who has the knowledge?”
    

    View Slide

15. View Slide

16. Who needs documentation, anyway?
    

    View Slide

17. Are we solving the right problem?
    

    View Slide

18. Solving problems with the documentation when
    documentation is not the answer
    

    View Slide

19. We document a thing
    where nobody will be looking for it
    

    View Slide

20. What to document?
    Business and domain
    High level architecture
    Low
    level design
    

    View Slide

21. what
    distinguish
    is documented
    how
    to document it
    from
    

    View Slide

22. Business and domain
    High level architecture
    Low level design
    

    View Slide

23. Decision Sustainability Piramid (DSP ™)
    Business and domain
    High level architecture
    Low level design
    

    View Slide

24. Decision Sustainability Piramid (DSP ™)
    Business and domain
    High level architecture
    Low level design
    patent pending
    

    View Slide

25. What to document?
    Business and domain
    High level architecture
    Low
    level design
    

    View Slide

26. a flexible workshop format for
    collaborative exploration of complex
    business domains,
    beyond silo and specialisation boundaries.
    

    View Slide

27. EventStorming
    a flexible workshop format for
    collaborative exploration of complex
    business domains,
    beyond silo and specialisation boundaries.
    

    View Slide

28. View Slide

29. View Slide

30. View Slide

31. View Slide

32. View Slide

33. View Slide

34. View Slide

35. View Slide

36. View Slide

37. View Slide

38. View Slide

39. View Slide

40. View Slide

41. View Slide

42. View Slide

43. Product is:
    ● Item in sales pitch
    ● Inventory Element in API
    ● Inventory Element, Item and Product in the code
    

    View Slide

44. Why does it matter?
    

    View Slide

45. View Slide

46. View Slide

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
    

    View Slide

48. Ubiquitous language
    

    View Slide

49. View Slide

50. What to document?
    Business and domain
    High level architecture
    Low
    level design
    

    View Slide

51. What is your architecture?
    

    View Slide

52. What is your architecture?
    How do you solve your business goals with
    technology?
    

    View Slide

53. How vs Why
    

    View Slide

54. but document
    Let the architecture emerge
    what has emerged!
    

    View Slide

55. Architecture is decisions
    

    View Slide

56. Architecture Decision Record
    

    View Slide

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/
    

    View Slide

58. D
    A
    C
    I
    

    View Slide

59. Driver
    A
    C
    I
    

    View Slide

60. Driver
    Approver
    C
    I
    

    View Slide

61. Driver
    Approver
    Contributors
    I
    

    View Slide

62. Driver
    Approver
    Contributors
    Informed
    

    View Slide

63. View Slide

64. What to document?
    Business and domain
    High level architecture
    Low
    level design
    

    View Slide

65. Main villains
    

    View Slide

66. Villain nr 1 - outdated wiki pages
    

    View Slide

67. Villain nr 2 - tribal knowledge
    

    View Slide

68. Villain nr 3 - confusing design
    

    View Slide

69. Code design documentation? Sure, but...
    

    View Slide

70. API Code design documentation? Sure, but...
    

    View Slide

71. Discoverability is better
    https://blog.jooq.org/2013/11/22/using-jooq-with-groovy/
    

    View Slide

72. Recall vs Recognition
    

    View Slide

73. Strongly Typed
    

    View Slide

74. Stringly Strongly Typed
    

    View Slide

75. String#regionMatches(int, String, int, int)
    String#regionMatches(boolean, int, String, int, int)
    

    View Slide

76. Simplicity is better
    

    View Slide

77. Simplicity is better
    It is far more difficult to be simple than to be complicated
    John Ruskin
    

    View Slide

78. Consistency is better
    

    View Slide

79. public interface Stream {
    Stream map(Function super T, ? extends R> mapper);
    Stream flatMap(Function super T, ? extends Stream extends R>> mapper);
    }
    public interface Optional {
    Optional map(Function super T, ? extends U> mapper);
    Optional flatMap(Function super T, ? extends Optional extends U>> mapper);
    }
    public interface CompletionStage {
    CompletionStage thenCompose (Function super T, ? extends U> fn);
    CompletionStage thenApply (Function super T, ? extends CompletionStage extends U>> fn);
    }
    

    View Slide

80. Consistency is the king!
    

    View Slide

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
    

    View Slide

82. The User Experience of
    documentation
    

    View Slide

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/
    

    View Slide

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?
    

    View Slide

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?
    

    View Slide

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?
    

    View Slide

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?
    

    View Slide

88. Thank you!
    Zbyszko Papierski
    #dynatrace @zpapierski
    Jakub Marchwicki
    @kubem #casumo
    

    View Slide

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
    

    View Slide