SlideShare a Scribd company logo
Inclusion Starts

With Docs
A talk about docs, Elixir, and user empathy
by Pete Gamache.
Presented at the first EMPEX LA conference,
10 November 2018.
Hello!
What is this?
• A short guide to getting the most out of Elixir's
built-in docs system, ExDoc
• A love letter to the authors of great docs
Some Ques7ons
• Do you want to have to fully understand someone
else's code in order to use it?
Some Ques7ons
• Do you trust the code of developers who could not or
would not describe it in plain English?
Some Ques7ons
• Do you want to restrict your audience to "geniuses"?
Some Ques7ons
• Do you want other people to fix and improve your
code, at no cost to you??
Name some great docs
Elixir Has Great Docs
• They look good
• Modules explain their purpose
• Functions explain their semantics
• Sample code everywhere
ExDoc Cheat Sheet
• Write your docs in Markdown, inline with your
source code
• Indent sample code four spaces from the rest
• Add ex_doc to your project dependencies in mix.exs
• mix docs generates HTML docs in doc/
• mix hex.publish docs publishes docs for a Hex
module to hexdocs.pm
Write Docs in Markdown
Moduledocs
• Explain the purpose of a module (or project)
• Sample code illustrates common usage
• Installation instructions
• In lesser languages, we'd use a README for this
TIP! Install Instruc7ons
• Scenario: you add a feature and increase the version
number of your project
• Oh no! You forget to change it in the @moduledoc,
so your docs are telling people to install an old
version
• Solution: variable interpolation in @moduledoc,
using ~s sigil (not ~S) and
#{MyApp.Mixfile.project[:version]}
Func7on Docs
• Provide the intent and specification for each
function
• ...So be specific! Esp. input and output types
• Sample code goes deeper than moduledoc
• Use @doc just before function definition
Doctests
• Problem: sample code in docs can go stale
• Elixir's solution: execute sample code as tests
• Rules are fairly simple: code starts with iex>, results
don't, no blank lines allowed
• Just put doctest MyApp.Modulename in one of your
test files
TIP! Doctests
• Always add doctest MyApp.Modulename to your
tests, even when you have no doctests
• Harmless with no doctests
• Avoids having unevaluated doctests later
• Also "good" for test coverage. Don't ask me why
Data Types
• String.starts_with?(string, prefix) is pretty clear already
• Many functions are not so lucky
• In languages with static typing, this is solved
automatically
• We're not using one of those languages, so we need to do
a tiny bit of work in order to ensure that a function's
input and output data types are obvious
• Elixir and Erlang's solution: Typespecs
Dialyzer
• Typespecs aren't only for docs
• Dialyzer is Erlang's "discrepancy analyzer"
• Add dialyxir to your mix.exs deps to use it in Elixir
• TL;DR you write typespecs, then run mix dialyzer,
then Erlang tells you if you were lying
Source Code
• Sometimes you just need to RTFS
• Usually not that hard to Google "<projectname>
github", plow into lib/, find the module in question,
grep for function name
• Come on, are you kidding me? What a PITA
• Elixir's solution: ExDoc supports Github repos
natively, via --source-url option
• ...And with a Mix task alias, automatically
Epilogue
We Have Great Docs
• Module's purpose is explained, with examples
• Functions are explained in depth, with examples
• These examples never go stale
• Dialyzer keeps us honest
• One-click access to source code
• And it all looks sharp
Read All About It!
• https://hexdocs.pm/ex_doc/readme.html
• https://hexdocs.pm/elixir/typespecs.html
• https://github.com/jeremyjh/dialyxir
Thanks!!
Pete Gamache
@gamache
pete@gamache.org

More Related Content

What's hot

Zoo of domain-specific languages
Zoo of domain-specific languagesZoo of domain-specific languages
Zoo of domain-specific languages
Mikhail Barash
 
Swift vs. Language X
Swift vs. Language XSwift vs. Language X
Swift vs. Language X
Scott Wlaschin
 
Code Generation in Perl
Code Generation in PerlCode Generation in Perl
Code Generation in Perl
Ian Kluft
 
JetBrains MPS
JetBrains MPSJetBrains MPS
Coding Standard And Code Review
Coding Standard And Code ReviewCoding Standard And Code Review
Coding Standard And Code Review
Milan Vukoje
 
5 hs mpostcustomizationrenefonseca
5 hs mpostcustomizationrenefonseca5 hs mpostcustomizationrenefonseca
5 hs mpostcustomizationrenefonseca
ssuserfadb24
 
Using ANTLR on real example - convert "string combined" queries into paramete...
Using ANTLR on real example - convert "string combined" queries into paramete...Using ANTLR on real example - convert "string combined" queries into paramete...
Using ANTLR on real example - convert "string combined" queries into paramete...
Alexey Diyan
 
Xtext beyond the defaults - how to tackle performance problems
Xtext beyond the defaults -  how to tackle performance problemsXtext beyond the defaults -  how to tackle performance problems
Xtext beyond the defaults - how to tackle performance problems
Holger Schill
 
How does intellisense work?
How does intellisense work?How does intellisense work?
How does intellisense work?
Adam Friedman
 
Programming Paradigm & Languages
Programming Paradigm & LanguagesProgramming Paradigm & Languages
Programming Paradigm & Languages
Gaditek
 
Lecture 10 software development
Lecture 10 software developmentLecture 10 software development
Lecture 10 software developmentJehanzaib Yousuf
 
Haskell Tour (Part 1)
Haskell Tour (Part 1)Haskell Tour (Part 1)
Haskell Tour (Part 1)
William Taysom
 
Erlang, LFE, Joxa and Elixir: Established and Emerging Languages in the Erlan...
Erlang, LFE, Joxa and Elixir: Established and Emerging Languages in the Erlan...Erlang, LFE, Joxa and Elixir: Established and Emerging Languages in the Erlan...
Erlang, LFE, Joxa and Elixir: Established and Emerging Languages in the Erlan...
Brian Troutwine
 
Hack in the Box GSEC 2016 - Reverse Engineering Swift Applications
Hack in the Box GSEC 2016 - Reverse Engineering Swift ApplicationsHack in the Box GSEC 2016 - Reverse Engineering Swift Applications
Hack in the Box GSEC 2016 - Reverse Engineering Swift Applications
eightbit
 
ANTLR4 and its testing
ANTLR4 and its testingANTLR4 and its testing
ANTLR4 and its testing
Knoldus Inc.
 
DSL explained _
DSL explained _DSL explained _
DSL explained _
Dmitry Kandalov
 
Python Programming
Python ProgrammingPython Programming
Python Programming
RenieMathews
 
A great clash of symbols
A great clash of symbolsA great clash of symbols
A great clash of symbols
Greg Sohl
 
2018-09 - F# and Fable
2018-09 - F# and Fable2018-09 - F# and Fable
2018-09 - F# and Fable
Eamonn Boyle
 

What's hot (20)

Zoo of domain-specific languages
Zoo of domain-specific languagesZoo of domain-specific languages
Zoo of domain-specific languages
 
Swift vs. Language X
Swift vs. Language XSwift vs. Language X
Swift vs. Language X
 
Code Generation in Perl
Code Generation in PerlCode Generation in Perl
Code Generation in Perl
 
JetBrains MPS
JetBrains MPSJetBrains MPS
JetBrains MPS
 
Coding Standard And Code Review
Coding Standard And Code ReviewCoding Standard And Code Review
Coding Standard And Code Review
 
5 hs mpostcustomizationrenefonseca
5 hs mpostcustomizationrenefonseca5 hs mpostcustomizationrenefonseca
5 hs mpostcustomizationrenefonseca
 
Lecture 8
Lecture 8Lecture 8
Lecture 8
 
Using ANTLR on real example - convert "string combined" queries into paramete...
Using ANTLR on real example - convert "string combined" queries into paramete...Using ANTLR on real example - convert "string combined" queries into paramete...
Using ANTLR on real example - convert "string combined" queries into paramete...
 
Xtext beyond the defaults - how to tackle performance problems
Xtext beyond the defaults -  how to tackle performance problemsXtext beyond the defaults -  how to tackle performance problems
Xtext beyond the defaults - how to tackle performance problems
 
How does intellisense work?
How does intellisense work?How does intellisense work?
How does intellisense work?
 
Programming Paradigm & Languages
Programming Paradigm & LanguagesProgramming Paradigm & Languages
Programming Paradigm & Languages
 
Lecture 10 software development
Lecture 10 software developmentLecture 10 software development
Lecture 10 software development
 
Haskell Tour (Part 1)
Haskell Tour (Part 1)Haskell Tour (Part 1)
Haskell Tour (Part 1)
 
Erlang, LFE, Joxa and Elixir: Established and Emerging Languages in the Erlan...
Erlang, LFE, Joxa and Elixir: Established and Emerging Languages in the Erlan...Erlang, LFE, Joxa and Elixir: Established and Emerging Languages in the Erlan...
Erlang, LFE, Joxa and Elixir: Established and Emerging Languages in the Erlan...
 
Hack in the Box GSEC 2016 - Reverse Engineering Swift Applications
Hack in the Box GSEC 2016 - Reverse Engineering Swift ApplicationsHack in the Box GSEC 2016 - Reverse Engineering Swift Applications
Hack in the Box GSEC 2016 - Reverse Engineering Swift Applications
 
ANTLR4 and its testing
ANTLR4 and its testingANTLR4 and its testing
ANTLR4 and its testing
 
DSL explained _
DSL explained _DSL explained _
DSL explained _
 
Python Programming
Python ProgrammingPython Programming
Python Programming
 
A great clash of symbols
A great clash of symbolsA great clash of symbols
A great clash of symbols
 
2018-09 - F# and Fable
2018-09 - F# and Fable2018-09 - F# and Fable
2018-09 - F# and Fable
 

Similar to EMPEX LA 2018 - Inclusion Starts with Docs

Orthogonality: A Strategy for Reusable Code
Orthogonality: A Strategy for Reusable CodeOrthogonality: A Strategy for Reusable Code
Orthogonality: A Strategy for Reusable Codersebbe
 
JOSA TechTalks - Compilers, Transpilers, and Why You Should Care
JOSA TechTalks - Compilers, Transpilers, and Why You Should CareJOSA TechTalks - Compilers, Transpilers, and Why You Should Care
JOSA TechTalks - Compilers, Transpilers, and Why You Should Care
Jordan Open Source Association
 
Programming Languages #devcon2013
Programming Languages #devcon2013Programming Languages #devcon2013
Programming Languages #devcon2013Iván Montes
 
Does The Delphi IDE Narrow You? Extend It! - ITDevConX European Delphi Confer...
Does The Delphi IDE Narrow You? Extend It! - ITDevConX European Delphi Confer...Does The Delphi IDE Narrow You? Extend It! - ITDevConX European Delphi Confer...
Does The Delphi IDE Narrow You? Extend It! - ITDevConX European Delphi Confer...
Marco Breveglieri
 
NetWork - 15.10.2011 - Applied code generation in .NET
NetWork - 15.10.2011 - Applied code generation in .NET NetWork - 15.10.2011 - Applied code generation in .NET
NetWork - 15.10.2011 - Applied code generation in .NET Dmytro Mindra
 
Build software like a bag of marbles, not a castle of LEGO®
Build software like a bag of marbles, not a castle of LEGO®Build software like a bag of marbles, not a castle of LEGO®
Build software like a bag of marbles, not a castle of LEGO®
Hannes Lowette
 
Getting Started with the TypeScript Language
Getting Started with the TypeScript LanguageGetting Started with the TypeScript Language
Getting Started with the TypeScript Language
Gil Fink
 
Like SpecFlow
Like SpecFlowLike SpecFlow
Like SpecFlow
Dmitry Dorogoy
 
Introduction to the intermediate Python - v1.1
Introduction to the intermediate Python - v1.1Introduction to the intermediate Python - v1.1
Introduction to the intermediate Python - v1.1
Andrei KUCHARAVY
 
Add-On Development: EE Expects that Every Developer will do his Duty
Add-On Development: EE Expects that Every Developer will do his DutyAdd-On Development: EE Expects that Every Developer will do his Duty
Add-On Development: EE Expects that Every Developer will do his Duty
reedmaniac
 
Elixir Brasil 2019 - Quality: A Panacéia para seu código Elixir
Elixir Brasil 2019 - Quality:  A Panacéia para seu código ElixirElixir Brasil 2019 - Quality:  A Panacéia para seu código Elixir
Elixir Brasil 2019 - Quality: A Panacéia para seu código Elixir
Weverton Timoteo
 
Software development fundamentals
Software development fundamentalsSoftware development fundamentals
Software development fundamentals
Alfred Jett Grandeza
 
Lecture 2: ES6 / ES2015 Slide
Lecture 2: ES6 / ES2015 SlideLecture 2: ES6 / ES2015 Slide
Lecture 2: ES6 / ES2015 Slide
Kobkrit Viriyayudhakorn
 
Professional Help for PowerShell Modules
Professional Help for PowerShell ModulesProfessional Help for PowerShell Modules
Professional Help for PowerShell Modules
June Blender
 
Add-On Development: EE Expects that Every Developer will do his Duty
Add-On Development: EE Expects that Every Developer will do his DutyAdd-On Development: EE Expects that Every Developer will do his Duty
Add-On Development: EE Expects that Every Developer will do his Duty
Leslie Doherty
 
JSR 335 / java 8 - update reference
JSR 335 / java 8 - update referenceJSR 335 / java 8 - update reference
JSR 335 / java 8 - update reference
sandeepji_choudhary
 
Introduction to Functional Programming
Introduction to Functional ProgrammingIntroduction to Functional Programming
Introduction to Functional Programming
Dave Fancher
 

Similar to EMPEX LA 2018 - Inclusion Starts with Docs (20)

Orthogonality: A Strategy for Reusable Code
Orthogonality: A Strategy for Reusable CodeOrthogonality: A Strategy for Reusable Code
Orthogonality: A Strategy for Reusable Code
 
JOSA TechTalks - Compilers, Transpilers, and Why You Should Care
JOSA TechTalks - Compilers, Transpilers, and Why You Should CareJOSA TechTalks - Compilers, Transpilers, and Why You Should Care
JOSA TechTalks - Compilers, Transpilers, and Why You Should Care
 
Programming Languages #devcon2013
Programming Languages #devcon2013Programming Languages #devcon2013
Programming Languages #devcon2013
 
Does The Delphi IDE Narrow You? Extend It! - ITDevConX European Delphi Confer...
Does The Delphi IDE Narrow You? Extend It! - ITDevConX European Delphi Confer...Does The Delphi IDE Narrow You? Extend It! - ITDevConX European Delphi Confer...
Does The Delphi IDE Narrow You? Extend It! - ITDevConX European Delphi Confer...
 
NetWork - 15.10.2011 - Applied code generation in .NET
NetWork - 15.10.2011 - Applied code generation in .NET NetWork - 15.10.2011 - Applied code generation in .NET
NetWork - 15.10.2011 - Applied code generation in .NET
 
Build software like a bag of marbles, not a castle of LEGO®
Build software like a bag of marbles, not a castle of LEGO®Build software like a bag of marbles, not a castle of LEGO®
Build software like a bag of marbles, not a castle of LEGO®
 
Getting Started with the TypeScript Language
Getting Started with the TypeScript LanguageGetting Started with the TypeScript Language
Getting Started with the TypeScript Language
 
Like SpecFlow
Like SpecFlowLike SpecFlow
Like SpecFlow
 
l2-es6-160830040119.pdf
l2-es6-160830040119.pdfl2-es6-160830040119.pdf
l2-es6-160830040119.pdf
 
Introduction to the intermediate Python - v1.1
Introduction to the intermediate Python - v1.1Introduction to the intermediate Python - v1.1
Introduction to the intermediate Python - v1.1
 
Add-On Development: EE Expects that Every Developer will do his Duty
Add-On Development: EE Expects that Every Developer will do his DutyAdd-On Development: EE Expects that Every Developer will do his Duty
Add-On Development: EE Expects that Every Developer will do his Duty
 
presentation
presentationpresentation
presentation
 
Elixir Brasil 2019 - Quality: A Panacéia para seu código Elixir
Elixir Brasil 2019 - Quality:  A Panacéia para seu código ElixirElixir Brasil 2019 - Quality:  A Panacéia para seu código Elixir
Elixir Brasil 2019 - Quality: A Panacéia para seu código Elixir
 
Software development fundamentals
Software development fundamentalsSoftware development fundamentals
Software development fundamentals
 
Lecture 2: ES6 / ES2015 Slide
Lecture 2: ES6 / ES2015 SlideLecture 2: ES6 / ES2015 Slide
Lecture 2: ES6 / ES2015 Slide
 
Professional Help for PowerShell Modules
Professional Help for PowerShell ModulesProfessional Help for PowerShell Modules
Professional Help for PowerShell Modules
 
Add-On Development: EE Expects that Every Developer will do his Duty
Add-On Development: EE Expects that Every Developer will do his DutyAdd-On Development: EE Expects that Every Developer will do his Duty
Add-On Development: EE Expects that Every Developer will do his Duty
 
presentation
presentationpresentation
presentation
 
JSR 335 / java 8 - update reference
JSR 335 / java 8 - update referenceJSR 335 / java 8 - update reference
JSR 335 / java 8 - update reference
 
Introduction to Functional Programming
Introduction to Functional ProgrammingIntroduction to Functional Programming
Introduction to Functional Programming
 

Recently uploaded

Exploring Innovations in Data Repository Solutions - Insights from the U.S. G...
Exploring Innovations in Data Repository Solutions - Insights from the U.S. G...Exploring Innovations in Data Repository Solutions - Insights from the U.S. G...
Exploring Innovations in Data Repository Solutions - Insights from the U.S. G...
Globus
 
Globus Compute wth IRI Workflows - GlobusWorld 2024
Globus Compute wth IRI Workflows - GlobusWorld 2024Globus Compute wth IRI Workflows - GlobusWorld 2024
Globus Compute wth IRI Workflows - GlobusWorld 2024
Globus
 
BoxLang: Review our Visionary Licenses of 2024
BoxLang: Review our Visionary Licenses of 2024BoxLang: Review our Visionary Licenses of 2024
BoxLang: Review our Visionary Licenses of 2024
Ortus Solutions, Corp
 
Climate Science Flows: Enabling Petabyte-Scale Climate Analysis with the Eart...
Climate Science Flows: Enabling Petabyte-Scale Climate Analysis with the Eart...Climate Science Flows: Enabling Petabyte-Scale Climate Analysis with the Eart...
Climate Science Flows: Enabling Petabyte-Scale Climate Analysis with the Eart...
Globus
 
Gamify Your Mind; The Secret Sauce to Delivering Success, Continuously Improv...
Gamify Your Mind; The Secret Sauce to Delivering Success, Continuously Improv...Gamify Your Mind; The Secret Sauce to Delivering Success, Continuously Improv...
Gamify Your Mind; The Secret Sauce to Delivering Success, Continuously Improv...
Shahin Sheidaei
 
Innovating Inference - Remote Triggering of Large Language Models on HPC Clus...
Innovating Inference - Remote Triggering of Large Language Models on HPC Clus...Innovating Inference - Remote Triggering of Large Language Models on HPC Clus...
Innovating Inference - Remote Triggering of Large Language Models on HPC Clus...
Globus
 
De mooiste recreatieve routes ontdekken met RouteYou en FME
De mooiste recreatieve routes ontdekken met RouteYou en FMEDe mooiste recreatieve routes ontdekken met RouteYou en FME
De mooiste recreatieve routes ontdekken met RouteYou en FME
Jelle | Nordend
 
WSO2Con2024 - WSO2's IAM Vision: Identity-Led Digital Transformation
WSO2Con2024 - WSO2's IAM Vision: Identity-Led Digital TransformationWSO2Con2024 - WSO2's IAM Vision: Identity-Led Digital Transformation
WSO2Con2024 - WSO2's IAM Vision: Identity-Led Digital Transformation
WSO2
 
First Steps with Globus Compute Multi-User Endpoints
First Steps with Globus Compute Multi-User EndpointsFirst Steps with Globus Compute Multi-User Endpoints
First Steps with Globus Compute Multi-User Endpoints
Globus
 
Software Testing Exam imp Ques Notes.pdf
Software Testing Exam imp Ques Notes.pdfSoftware Testing Exam imp Ques Notes.pdf
Software Testing Exam imp Ques Notes.pdf
MayankTawar1
 
Strategies for Successful Data Migration Tools.pptx
Strategies for Successful Data Migration Tools.pptxStrategies for Successful Data Migration Tools.pptx
Strategies for Successful Data Migration Tools.pptx
varshanayak241
 
Globus Compute Introduction - GlobusWorld 2024
Globus Compute Introduction - GlobusWorld 2024Globus Compute Introduction - GlobusWorld 2024
Globus Compute Introduction - GlobusWorld 2024
Globus
 
How to Position Your Globus Data Portal for Success Ten Good Practices
How to Position Your Globus Data Portal for Success Ten Good PracticesHow to Position Your Globus Data Portal for Success Ten Good Practices
How to Position Your Globus Data Portal for Success Ten Good Practices
Globus
 
Multiple Your Crypto Portfolio with the Innovative Features of Advanced Crypt...
Multiple Your Crypto Portfolio with the Innovative Features of Advanced Crypt...Multiple Your Crypto Portfolio with the Innovative Features of Advanced Crypt...
Multiple Your Crypto Portfolio with the Innovative Features of Advanced Crypt...
Hivelance Technology
 
How Does XfilesPro Ensure Security While Sharing Documents in Salesforce?
How Does XfilesPro Ensure Security While Sharing Documents in Salesforce?How Does XfilesPro Ensure Security While Sharing Documents in Salesforce?
How Does XfilesPro Ensure Security While Sharing Documents in Salesforce?
XfilesPro
 
Large Language Models and the End of Programming
Large Language Models and the End of ProgrammingLarge Language Models and the End of Programming
Large Language Models and the End of Programming
Matt Welsh
 
Accelerate Enterprise Software Engineering with Platformless
Accelerate Enterprise Software Engineering with PlatformlessAccelerate Enterprise Software Engineering with Platformless
Accelerate Enterprise Software Engineering with Platformless
WSO2
 
Corporate Management | Session 3 of 3 | Tendenci AMS
Corporate Management | Session 3 of 3 | Tendenci AMSCorporate Management | Session 3 of 3 | Tendenci AMS
Corporate Management | Session 3 of 3 | Tendenci AMS
Tendenci - The Open Source AMS (Association Management Software)
 
Explore Modern SharePoint Templates for 2024
Explore Modern SharePoint Templates for 2024Explore Modern SharePoint Templates for 2024
Explore Modern SharePoint Templates for 2024
Sharepoint Designs
 
Prosigns: Transforming Business with Tailored Technology Solutions
Prosigns: Transforming Business with Tailored Technology SolutionsProsigns: Transforming Business with Tailored Technology Solutions
Prosigns: Transforming Business with Tailored Technology Solutions
Prosigns
 

Recently uploaded (20)

Exploring Innovations in Data Repository Solutions - Insights from the U.S. G...
Exploring Innovations in Data Repository Solutions - Insights from the U.S. G...Exploring Innovations in Data Repository Solutions - Insights from the U.S. G...
Exploring Innovations in Data Repository Solutions - Insights from the U.S. G...
 
Globus Compute wth IRI Workflows - GlobusWorld 2024
Globus Compute wth IRI Workflows - GlobusWorld 2024Globus Compute wth IRI Workflows - GlobusWorld 2024
Globus Compute wth IRI Workflows - GlobusWorld 2024
 
BoxLang: Review our Visionary Licenses of 2024
BoxLang: Review our Visionary Licenses of 2024BoxLang: Review our Visionary Licenses of 2024
BoxLang: Review our Visionary Licenses of 2024
 
Climate Science Flows: Enabling Petabyte-Scale Climate Analysis with the Eart...
Climate Science Flows: Enabling Petabyte-Scale Climate Analysis with the Eart...Climate Science Flows: Enabling Petabyte-Scale Climate Analysis with the Eart...
Climate Science Flows: Enabling Petabyte-Scale Climate Analysis with the Eart...
 
Gamify Your Mind; The Secret Sauce to Delivering Success, Continuously Improv...
Gamify Your Mind; The Secret Sauce to Delivering Success, Continuously Improv...Gamify Your Mind; The Secret Sauce to Delivering Success, Continuously Improv...
Gamify Your Mind; The Secret Sauce to Delivering Success, Continuously Improv...
 
Innovating Inference - Remote Triggering of Large Language Models on HPC Clus...
Innovating Inference - Remote Triggering of Large Language Models on HPC Clus...Innovating Inference - Remote Triggering of Large Language Models on HPC Clus...
Innovating Inference - Remote Triggering of Large Language Models on HPC Clus...
 
De mooiste recreatieve routes ontdekken met RouteYou en FME
De mooiste recreatieve routes ontdekken met RouteYou en FMEDe mooiste recreatieve routes ontdekken met RouteYou en FME
De mooiste recreatieve routes ontdekken met RouteYou en FME
 
WSO2Con2024 - WSO2's IAM Vision: Identity-Led Digital Transformation
WSO2Con2024 - WSO2's IAM Vision: Identity-Led Digital TransformationWSO2Con2024 - WSO2's IAM Vision: Identity-Led Digital Transformation
WSO2Con2024 - WSO2's IAM Vision: Identity-Led Digital Transformation
 
First Steps with Globus Compute Multi-User Endpoints
First Steps with Globus Compute Multi-User EndpointsFirst Steps with Globus Compute Multi-User Endpoints
First Steps with Globus Compute Multi-User Endpoints
 
Software Testing Exam imp Ques Notes.pdf
Software Testing Exam imp Ques Notes.pdfSoftware Testing Exam imp Ques Notes.pdf
Software Testing Exam imp Ques Notes.pdf
 
Strategies for Successful Data Migration Tools.pptx
Strategies for Successful Data Migration Tools.pptxStrategies for Successful Data Migration Tools.pptx
Strategies for Successful Data Migration Tools.pptx
 
Globus Compute Introduction - GlobusWorld 2024
Globus Compute Introduction - GlobusWorld 2024Globus Compute Introduction - GlobusWorld 2024
Globus Compute Introduction - GlobusWorld 2024
 
How to Position Your Globus Data Portal for Success Ten Good Practices
How to Position Your Globus Data Portal for Success Ten Good PracticesHow to Position Your Globus Data Portal for Success Ten Good Practices
How to Position Your Globus Data Portal for Success Ten Good Practices
 
Multiple Your Crypto Portfolio with the Innovative Features of Advanced Crypt...
Multiple Your Crypto Portfolio with the Innovative Features of Advanced Crypt...Multiple Your Crypto Portfolio with the Innovative Features of Advanced Crypt...
Multiple Your Crypto Portfolio with the Innovative Features of Advanced Crypt...
 
How Does XfilesPro Ensure Security While Sharing Documents in Salesforce?
How Does XfilesPro Ensure Security While Sharing Documents in Salesforce?How Does XfilesPro Ensure Security While Sharing Documents in Salesforce?
How Does XfilesPro Ensure Security While Sharing Documents in Salesforce?
 
Large Language Models and the End of Programming
Large Language Models and the End of ProgrammingLarge Language Models and the End of Programming
Large Language Models and the End of Programming
 
Accelerate Enterprise Software Engineering with Platformless
Accelerate Enterprise Software Engineering with PlatformlessAccelerate Enterprise Software Engineering with Platformless
Accelerate Enterprise Software Engineering with Platformless
 
Corporate Management | Session 3 of 3 | Tendenci AMS
Corporate Management | Session 3 of 3 | Tendenci AMSCorporate Management | Session 3 of 3 | Tendenci AMS
Corporate Management | Session 3 of 3 | Tendenci AMS
 
Explore Modern SharePoint Templates for 2024
Explore Modern SharePoint Templates for 2024Explore Modern SharePoint Templates for 2024
Explore Modern SharePoint Templates for 2024
 
Prosigns: Transforming Business with Tailored Technology Solutions
Prosigns: Transforming Business with Tailored Technology SolutionsProsigns: Transforming Business with Tailored Technology Solutions
Prosigns: Transforming Business with Tailored Technology Solutions
 

EMPEX LA 2018 - Inclusion Starts with Docs

  • 1. Inclusion Starts
 With Docs A talk about docs, Elixir, and user empathy by Pete Gamache. Presented at the first EMPEX LA conference, 10 November 2018.
  • 3. What is this? • A short guide to getting the most out of Elixir's built-in docs system, ExDoc • A love letter to the authors of great docs
  • 4. Some Ques7ons • Do you want to have to fully understand someone else's code in order to use it?
  • 5. Some Ques7ons • Do you trust the code of developers who could not or would not describe it in plain English?
  • 6. Some Ques7ons • Do you want to restrict your audience to "geniuses"?
  • 7. Some Ques7ons • Do you want other people to fix and improve your code, at no cost to you??
  • 9. Elixir Has Great Docs • They look good • Modules explain their purpose • Functions explain their semantics • Sample code everywhere
  • 10.
  • 11.
  • 12. ExDoc Cheat Sheet • Write your docs in Markdown, inline with your source code • Indent sample code four spaces from the rest • Add ex_doc to your project dependencies in mix.exs • mix docs generates HTML docs in doc/ • mix hex.publish docs publishes docs for a Hex module to hexdocs.pm
  • 13. Write Docs in Markdown
  • 14.
  • 15.
  • 16. Moduledocs • Explain the purpose of a module (or project) • Sample code illustrates common usage • Installation instructions • In lesser languages, we'd use a README for this
  • 17. TIP! Install Instruc7ons • Scenario: you add a feature and increase the version number of your project • Oh no! You forget to change it in the @moduledoc, so your docs are telling people to install an old version • Solution: variable interpolation in @moduledoc, using ~s sigil (not ~S) and #{MyApp.Mixfile.project[:version]}
  • 18.
  • 19. Func7on Docs • Provide the intent and specification for each function • ...So be specific! Esp. input and output types • Sample code goes deeper than moduledoc • Use @doc just before function definition
  • 20.
  • 21. Doctests • Problem: sample code in docs can go stale • Elixir's solution: execute sample code as tests • Rules are fairly simple: code starts with iex>, results don't, no blank lines allowed • Just put doctest MyApp.Modulename in one of your test files
  • 22. TIP! Doctests • Always add doctest MyApp.Modulename to your tests, even when you have no doctests • Harmless with no doctests • Avoids having unevaluated doctests later • Also "good" for test coverage. Don't ask me why
  • 23. Data Types • String.starts_with?(string, prefix) is pretty clear already • Many functions are not so lucky • In languages with static typing, this is solved automatically • We're not using one of those languages, so we need to do a tiny bit of work in order to ensure that a function's input and output data types are obvious • Elixir and Erlang's solution: Typespecs
  • 24.
  • 25.
  • 26. Dialyzer • Typespecs aren't only for docs • Dialyzer is Erlang's "discrepancy analyzer" • Add dialyxir to your mix.exs deps to use it in Elixir • TL;DR you write typespecs, then run mix dialyzer, then Erlang tells you if you were lying
  • 27. Source Code • Sometimes you just need to RTFS • Usually not that hard to Google "<projectname> github", plow into lib/, find the module in question, grep for function name • Come on, are you kidding me? What a PITA • Elixir's solution: ExDoc supports Github repos natively, via --source-url option • ...And with a Mix task alias, automatically
  • 28.
  • 29.
  • 30.
  • 32. We Have Great Docs • Module's purpose is explained, with examples • Functions are explained in depth, with examples • These examples never go stale • Dialyzer keeps us honest • One-click access to source code • And it all looks sharp
  • 33. Read All About It! • https://hexdocs.pm/ex_doc/readme.html • https://hexdocs.pm/elixir/typespecs.html • https://github.com/jeremyjh/dialyxir