Preventing Brain Freeze: Onboarding New Developers with Living Documentation

Your first contribution to an existing in-house application can be like eating ice cream too quickly on a hot summer’s day – your excitement and enthusiasm result in a painful headache as you struggle to understand the domain and navigate the codebase. Elixir and the surrounding ecosystem have an excellent reputation for beautiful documentation and onboarding tools, but these practices don’t always migrate to in-house applications hidden from public view.

Together, we’ll discover the principles and practices of living documentation and how Elixir’s tooling supports its implementation. At the end of the presentation, you’ll leave with a set of techniques and methods to elevate your application’s onboarding experience to prevent the next ice cream headache.

Transcript

1. ELIXIRCONF 2021 Onboarding New Developers with Living Documentation PREVENTING BRAIN FREEZE @nicholasjhenry
2. ONBOARDING
3. THE PROCESS OF INTRODUCING A NEWLY HIRED EMPLOYEE INTO AN ORGANIZATION
4. THE PROCESS OF INTRODUCING A NEWLY HIRED DEVELOPER ONTO A PROJECT
5. PROBLEM DOMAIN VS SOLUTION DOMAIN
6. ONBOARDING IS KNOWLEDGE SHARING
7. DOCUMENTATION 
 FOR ASYNC 
 KNOWLEDGE SHARING
8. TRADITIONAL DOCUMENTATION
9. - Reliabl e - Low Effor t - Collaborativ e - Insightful LIVING DOCUMENTATION
10. LEVERAGE
 AUGMEN T CURATE YOUR SOURCE CODE FOR ONBOARDING
11. YOUR MOTIVATION FOR LIVING DOCUMENTATION
12. LEADING AND LAGGING INDICATORS
13. "YOUR OUTCOMES ARE A LAGGING MEASURE OF YOUR HABITS. YOUR NET WORTH IS A LAGGING MEASURE OF YOUR FINANCIAL HABITS. YOUR WEIGHT IS A LAGGING MEASURE OF YOUR EATING HABITS. YOUR CLUTTER IS A LAGGING MEASURE OF YOUR CLEANING HABITS." JAMES CLEAR, ATOMIC HABITS
14. YOUR TEAMS VELOCITY IS A LAGGING MEASURE OF YOUR SOFTWARE DEVELOPMENT PRACTICES
15. YOUR TEAMS ONBOARDING EXPERIENCE IS A LAGGING MEASURE OF YOUR KNOWLEDGE SHARING PRACTICES
16. TEST-DRIVEN DEVELOPMENT
17. "THE GUIDANCE OR PRESSURE THAT TEST-DRIVEN DEVELOPMENT PLACES ON YOUR SOFTWARE DESIGN" JB RAINSBERGER, INTEGRATED TESTS ARE A SCAM
18. “…IS THE LITTLE VOICE IN THE BACK OF YOUR HEAD MADE MANIFEST BY A CRAPPY TEST WITH TOO MUCH SETUP" KELLY SUTTON
19. WILL I EVER BENEFIT FROM KNOWLEDGE SHARING?
20. README-DRIVEN DEVELOPMENT
21. "WRITING A README IS ABSOLUTELY ESSENTIAL TO WRITING GOOD SOFTWARE. UNTIL YOU’VE WRITTEN ABOUT YOUR SOFTWARE, YOU HAVE NO IDEA WHAT YOU’LL BE CODING." TOM PRESTON-WERNER
22. "WRITE YOUR README FIRST. FIRST. AS IN, BEFORE YOU WRITE ANY CODE OR TESTS OR BEHAVIORS OR STORIES OR ANYTHING." TOM PRESTON-WERNER
23. README-DRIVEN DEVELOPMENT IS 
 YOUR RUBBER DUCK
24. "A VERY SIMPLE BUT PARTICULARLY USEFUL TECHNIQUE FOR FINDING THE CAUSE OF A PROBLEM IS SIMPLY TO EXPLAIN IT TO SOMEONE ELSE. THE OTHER PERSON SHOULD LOOK OVER YOUR SHOULDER AT THE SCREEN, AND NOD HIS OR HER HEAD CONSTANTLY (LIKE A RUBBER DUCK BOBBING UP AND DOWN IN A BATHTUB). THEY DO NOT NEED TO SAY A WORD; THE SIMPLE ACT OF EXPLAINING, STEP BY STEP, WHAT THE CODE IS SUPPOSED TO DO OFTEN CAUSES THE PROBLEM TO LEAP OFF THE SCREEN AND ANNOUNCE ITSELF. ” THE PRAGMATIC PROGRAMMERS
25. BETTER NAMES, BETTER DESIG N YOUR LEADING INDICATOR FOR KNOWLEDGE SHARING
26. LIVING DOCUMENTATION IN ELIXIR
27. POCKETS PLATFORM:
 THE EXAMPLE APPLICATION https://www.github.com/nicholasjhenry/pockets_platform
28. LEVERAGE
 AUGMEN T CURATE YOUR SOURCE CODE FOR ONBOARDING
29. EXDOC
30. @moduledoc
31. $ mix doc warning:documentation references file "./" but it does not exist README.md
32. $ mix compile — errors as warnings $ mix docs | (! grep warning)
33. A STORY FROM THE FIELD A slew of warnings during doc generation reduces confidence in documentation
34. PUBLISHING EXDOC
35. ENDPOINT.EX plug Plug.Static, at: "/", from: :pockets_web, gzip: false, only: ~w(css fonts images js vendors favicon.ico robots.txt doc) 👀
36. A STORY FROM THE FIELD Keep things that change together, close together, 
 including documentation
37. POCKETS_PLATFORM$ MIX DOC
38. -Time consumin g -Long single table of contents to navigat e -Single, global ex_doc con fi guration THE DOWNSIDES OF UMBRELLA DOCUMENTATION
39. pockets_platform$ ls -1d deps/phoenix* phoenix phoenix_ecto phoenix_html phoenix_live_reload phoenix_live_view phoenix_live_dashboard FOLLOW THE ECOSYSTEM FOR A BETTER WAY
40. $ MIX DOC #IGNORE CHILD APPS $ MIX CMD MIX DOCS
41. - Problem Domai n - Visio n - Stakeholder s - Business Capabilitie s - Solution Domai n - Catalog of Child Application s - Architecture UMBRELLA PROJECT README
42. LEVERAGE
 AUGMEN T CURATE YOUR SOURCE CODE FOR ONBOARDING
43. “A RATE OF RETURN (ROR) IS THE NET GAIN OR LOSS OF AN INVESTMENT OVER A SPECIFIED TIME PERIOD, EXPRESSED AS A PERCENTAGE OF THE INVESTMENT’S INITIAL COST. WHEN CALCULATING THE RATE OF RETURN, YOU ARE DETERMINING THE PERCENTAGE CHANGE FROM THE BEGINNING OF THE PERIOD UNTIL THE END.” INVESTOPEDIA
44. RATE OF RETURN def calculate(current_value, initial_value) do current_value |> Decimal.sub(initial_value) |> Decimal.div(initial_value) |> Decimal.mult(100) end PROBLEM DOMAIN SOLUTION DOMAIN
45. - Supplement with JavaScript librarie s - KaTeX: Math typesetting librar y - https://katex.org EXDOC + KATEX
46. EXDOC CONFIGURATION defmodule FinancialRatios.MixProject do use Mix.Project def project do [ app: :financial_ratios, # … # Docs name: "Financial Ratios", homepage_url: "../index.html", docs: docs() ] end def docs, do: #… end defp docs do [ before_closing_head_tag: &before_closing_head_tag/1, output: "../../doc/financial_ratios" ] end defp before_closing_head_tag(_format), do: include_math_typsetting_lib() defp include_math_typsetting_lib do """ <link rel="stylesheet" href="https://cdn.jsdelivr.net/ <script defer src="https://cdn.jsdelivr.net/npm/katex <script defer src="https://cdn.jsdelivr.net/npm/katex """ end 👀 1 👀 2 👀 3
47. defmodule FinancialRatios.RateOfReturn do @formula ~S| \text{Rate of return} = [\frac{(\text{Current value} - \text{Initial value})}{\text{Initial value}}]\times 100 | defstruct [:value] @moduledoc """ > A rate of return (RoR) is the net gain or loss of an investment over a specified time period, > expressed as a percentage of the investment’s initial cost. > > [Investopedia](https://www.investopedia.com/terms/r/rateofreturn.asp) The Formula for Rate of Return (RoR): $$#{@formula}$$ ## Example of a Rate of Return (RoR) > The rate of return can be calculated for any investment, dealing with any kind of asset. Let's > take the example of purchasing a home as a basic example for understanding how to calculate the > RoR. Say that you buy a house for $250,000 (for simplicity let's assume you pay 100% cash). iex> FinancialRatios.RateOfReturn.calculate(335_000, 250_000) #FinancialRatios.RateOfReturn<34.00%> """ # ... end 👀 1 👀 2 👀 3 👀 4
48. - mix doc s - ExDoc HTM L - MathML rendered by KaTeX GENERATED DOCUMENTATION WITH KATEX
49. LEVERAGE
 AUGMEN T CURATE YOUR SOURCE CODE FOR ONBOARDING
50. - Guided Tou r - Site-seeing Maps CURATION
51. “Custom runtimes: when executing Elixir code, you can either start a fresh Elixir instance, connect to an existing node, or run it inside an existing Elixir project, with access to all of its modules and dependencies.This means Livebook can be a great tool to provide live documentation for existing projects.” GUIDED TOUR 👀
52. # install $ mix escript.install hex \ 
 livebook 0.2.3 # start the server $ live server GUIDED TOUR 👀
53. GUIDED TOUR $ live server - Start a node in the context of a Mix project 👀
54. - Runtime to evaluate example s - Start a node in the context of a Mix project GUIDED TOUR 👀
55. - Examples are evaluate d - Implement a tour for the complete applicatio n - KaTeX support out of the box GUIDED TOUR 👀
56. A STORY FROM THE FIELD Use curation for manual verification steps
57. - Small Experiment s - README-Driven Developmen t - ExDoc and C I - LiveBook for Complex Domains NEXT STEPS
58. ONBOARDING IS KNOWLEDGE SHARING
59. THANK YO U @nicholasjhenry