Upgrade to Pro — share decks privately, control downloads, hide ads and more …

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.

B5405045448a182b8ee12236ec63d8b0?s=128

Jakub Marchwicki

May 16, 2019
Tweet

Transcript

  1. The Documentation Developer’s Torment Zbyszko Papierski #dynatrace @zpapierski Jakub Marchwicki

    @kubem #casumo
  2. None
  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)
  4. None
  5. None
  6. 2 = 1 + 1

  7. None
  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?”

  15. None
  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.
  28. None
  29. None
  30. None
  31. None
  32. None
  33. None
  34. None
  35. None
  36. None
  37. None
  38. None
  39. None
  40. None
  41. None
  42. None
  43. Product is: • Item in sales pitch • Inventory Element

    in API • Inventory Element, Item and Product in the code
  44. Why does it matter?

  45. None
  46. None
  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

  49. None
  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

  63. None
  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