![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]}](https://image.slidesharecdn.com/empex-la-2018-inclusion-docs-180210220543/85/EMPEX-LA-2018-Inclusion-Starts-with-Docs-17-320.jpg)
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.
- 2. Hello!
- 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??
- 8. Name some great docs
- 9. Elixir Has Great Docs • They look good • Modules explain their purpose • Functions explain their semantics • Sample code everywhere
- 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
- 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]}
- 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
- 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
- 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
- 31. Epilogue
- 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