What are the attributes of good documentation in Elixir?

Chat / Discussions
, ,
1

There is this section in the Elixir docs that talks about documentation. I would say it mostly covers how to effectively use ExDoc. But in the spirit of the library guidelines, what should our documentation guidelines be?

To kick things off:

  • What should/shouldn’t be in a project README/@moduledoc/@doc?
  • What public functions shouldn’t be documented?
  • What should/shouldn’t have type specs?
  • When should you document your types for type specs?
  • How do you document a GenServer? (e.g. child_spec, start_link, init, handle_call, etc)
  • How do you document callbacks? What about implementations of callbacks?
  • How do you document macro generated code?
  • How do you document your exceptions?
  • How do you document your protocols?
5 Likes
2

Related: it is extremely important that any documentation clearly includes a link where issues can be filed so that improvements can be made as easily as possible. E.g. if the documentation is ultimately stored in a Github repository, then include a link where users can fork the docs and submit updates. Without a clear feedback loop, the docs fundamentally broken imo.

1 Like