Preventing Brain Freeze: Onboarding New Developers with Living Documentation

Slide 1

Slide 1 text

ELIXIRCONF 2021 Onboarding New Developers with Living Documentation PREVENTING BRAIN FREEZE @nicholasjhenry

Slide 2

Slide 2 text

ONBOARDING

Slide 3

Slide 3 text

THE PROCESS OF INTRODUCING A NEWLY HIRED EMPLOYEE INTO AN ORGANIZATION

Slide 4

Slide 4 text

THE PROCESS OF INTRODUCING A NEWLY HIRED DEVELOPER ONTO A PROJECT

Slide 5

Slide 5 text

PROBLEM DOMAIN VS SOLUTION DOMAIN

Slide 6

Slide 6 text

ONBOARDING IS KNOWLEDGE SHARING

Slide 7

Slide 7 text

DOCUMENTATION   FOR ASYNC   KNOWLEDGE SHARING

Slide 8

Slide 8 text

TRADITIONAL DOCUMENTATION

Slide 9

Slide 9 text

- Reliabl e - Low Effor t - Collaborativ e - Insightful LIVING DOCUMENTATION

Slide 10

Slide 10 text

LEVERAGE  AUGMEN T CURATE YOUR SOURCE CODE FOR ONBOARDING

Slide 11

Slide 11 text

YOUR MOTIVATION FOR LIVING DOCUMENTATION

Slide 12

Slide 12 text

LEADING AND LAGGING INDICATORS

Slide 13

Slide 13 text

"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

Slide 14

Slide 14 text

YOUR TEAMS VELOCITY IS A LAGGING MEASURE OF YOUR SOFTWARE DEVELOPMENT PRACTICES

Slide 15

Slide 15 text

YOUR TEAMS ONBOARDING EXPERIENCE IS A LAGGING MEASURE OF YOUR KNOWLEDGE SHARING PRACTICES

Slide 16

Slide 16 text

TEST-DRIVEN DEVELOPMENT

Slide 17

Slide 17 text

"THE GUIDANCE OR PRESSURE THAT TEST-DRIVEN DEVELOPMENT PLACES ON YOUR SOFTWARE DESIGN" JB RAINSBERGER, INTEGRATED TESTS ARE A SCAM

Slide 18

Slide 18 text

“…IS THE LITTLE VOICE IN THE BACK OF YOUR HEAD MADE MANIFEST BY A CRAPPY TEST WITH TOO MUCH SETUP" KELLY SUTTON

Slide 19

Slide 19 text

WILL I EVER BENEFIT FROM KNOWLEDGE SHARING?

Slide 20

Slide 20 text

README-DRIVEN DEVELOPMENT

Slide 21

Slide 21 text

"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

Slide 22

Slide 22 text

"WRITE YOUR README FIRST. FIRST. AS IN, BEFORE YOU WRITE ANY CODE OR TESTS OR BEHAVIORS OR STORIES OR ANYTHING." TOM PRESTON-WERNER

Slide 23

Slide 23 text

README-DRIVEN DEVELOPMENT IS   YOUR RUBBER DUCK

Slide 24

Slide 24 text

"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

Slide 25

Slide 25 text

BETTER NAMES, BETTER DESIG N YOUR LEADING INDICATOR FOR KNOWLEDGE SHARING

Slide 26

Slide 26 text

LIVING DOCUMENTATION IN ELIXIR

Slide 27

Slide 27 text

POCKETS PLATFORM:  THE EXAMPLE APPLICATION https://www.github.com/nicholasjhenry/pockets_platform

Slide 28

Slide 28 text

LEVERAGE  AUGMEN T CURATE YOUR SOURCE CODE FOR ONBOARDING

Slide 29

Slide 29 text

EXDOC

Slide 30

Slide 30 text

@moduledoc

Slide 31

Slide 31 text

$ mix doc warning:documentation references file "./" but it does not exist README.md

Slide 32

Slide 32 text

$ mix compile — errors as warnings $ mix docs | (! grep warning)

Slide 33

Slide 33 text

A STORY FROM THE FIELD A slew of warnings during doc generation reduces confidence in documentation

Slide 34

Slide 34 text

PUBLISHING EXDOC

Slide 35

Slide 35 text

ENDPOINT.EX plug Plug.Static, at: "/", from: :pockets_web, gzip: false, only: ~w(css fonts images js vendors favicon.ico robots.txt doc) 👀

Slide 36

Slide 36 text

A STORY FROM THE FIELD Keep things that change together, close together,   including documentation

Slide 37

Slide 37 text

POCKETS_PLATFORM$ MIX DOC

Slide 38

Slide 38 text

-Time consumin g -Long single table of contents to navigat e -Single, global ex_doc con fi guration THE DOWNSIDES OF UMBRELLA DOCUMENTATION

Slide 39

Slide 39 text

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

Slide 40

Slide 40 text

$ MIX DOC #IGNORE CHILD APPS $ MIX CMD MIX DOCS

Slide 41

Slide 41 text

- Problem Domai n - Visio n - Stakeholder s - Business Capabilitie s - Solution Domai n - Catalog of Child Application s - Architecture UMBRELLA PROJECT README

Slide 42

Slide 42 text

LEVERAGE  AUGMEN T CURATE YOUR SOURCE CODE FOR ONBOARDING

Slide 43

Slide 43 text

“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

Slide 44

Slide 44 text

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

Slide 45

Slide 45 text

- Supplement with JavaScript librarie s - KaTeX: Math typesetting librar y - https://katex.org EXDOC + KATEX

Slide 46

Slide 46 text

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 """

Slide 47

Slide 47 text

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

Slide 48

Slide 48 text

- mix doc s - ExDoc HTM L - MathML rendered by KaTeX GENERATED DOCUMENTATION WITH KATEX

Slide 49

Slide 49 text

LEVERAGE  AUGMEN T CURATE YOUR SOURCE CODE FOR ONBOARDING

Slide 50

Slide 50 text

- Guided Tou r - Site-seeing Maps CURATION

Slide 51

Slide 51 text

“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 👀

Slide 52

Slide 52 text

# install $ mix escript.install hex \   livebook 0.2.3 # start the server $ live server GUIDED TOUR 👀

Slide 53

Slide 53 text

GUIDED TOUR $ live server - Start a node in the context of a Mix project 👀

Slide 54

Slide 54 text

- Runtime to evaluate example s - Start a node in the context of a Mix project GUIDED TOUR 👀

Slide 55

Slide 55 text

- Examples are evaluate d - Implement a tour for the complete applicatio n - KaTeX support out of the box GUIDED TOUR 👀

Slide 56

Slide 56 text

A STORY FROM THE FIELD Use curation for manual verification steps

Slide 57

Slide 57 text

- Small Experiment s - README-Driven Developmen t - ExDoc and C I - LiveBook for Complex Domains NEXT STEPS