EMPEX LA 2018 - Inclusion Starts with Docs by Pete Gamache

EMPEX LA 2018 - Inclusion Starts with Docs by Pete Gamache Great documentation is the single most powerful tool for increasing inclusion in a project. Docs can level the playing field between beginners and experts, providing everyone a better understanding of using and contributing to a library. The feeling of creating a project, putting it out there, and watching people contribute to it is breathtaking -- it's one of the things that gets people hooked on participating in the free software ecosystem. High-quality docs get a project, and its creator, to that point faster. Lucky for us, Elixir has best-in-class features for authoring and generating online documentation. In this talk, we'll examine and demonstrate Elixir's doc system, covering in particular: An introduction to ExDoc Top level project docs using @moduledoc Function docs using @doc Executable code samples using doctests Type annotations and docs using typespecs Linking your docs to your source code Magically auto-updating install instructions Documentation techniques and tactics for other kinds of projects (e.g. HTTP APIs) This talk has two goals: to show the power of Elixir's built-in docs system, and more importantly to get folks excited about how strongly fantastic docs can improve a project and its community. About Pete: Pete is CTO at Appcues, where Elixir has been a boring part of the platform for two years and counting (and that's high praise). He enjoys pattern-matching, immutable data structures, and long walks on the beach. Follow him on Twitter.