$30 off During Our Annual Pro Sale. View Details »

Developers Torment: The Documentation

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.

Jakub Marchwicki

May 16, 2019
Tweet

More Decks by Jakub Marchwicki

Other Decks in Technology

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