Hack The Docs

"Hack The Docs" is a collaborative editing project, focused on improving Elixir's online documentation. This page summarizes the project's objectives, approach, and schedule.

Objectives

Elixir's documentation entries (eg, @doc, @moduledoc) vary in quality. Some are clear, comprehensive, and useful; others, not so much. Making all of the documentation perfect is an unrealistic goal, but we can (and should!) improve the most neglected cases. Ideally, each @doc entry should contain:

  • a clean, clear description of the function's purpose

  • at least one working example, preferably in IEx format

Note: The discussion above is framed in terms of functions. Adjust accordingly for exceptions, macros, modules, protocols, etc.

Approach

Volunteers gather (either physically or virtually) to work on the Elixir documentation. Attendees tackle sections (eg, the Atom Module), adding examples, clarifying text, improving the format, removing cruft, etc. Virtual meetings are held on IRC (#elixir-lang). Physical meetings can be anywhere; feel free to schedule one!

Anyone is welcome (nay, encouraged!) to work on any part of the documentation. However, to assist in coordination, there is a status page for each currently active area. Please use this page to indicate the fact that you are working on (say) a module:

Plausible results go, as usual, to GitHub. Per José Valim:

There isn't much process. Just send a pull request that follows generally known guidelines, like:

  1. Good commit messages

  1. Focused: you should, for example, keep your changes in a single chapter
    (unless you are doing something structural to all of them).

Note: Please see the Editing HowTo for detailed instructions.


This wiki page is maintained by Rich Morin, an independent consultant specializing in software design, development, and documentation. Please feel free to email comments, inquiries, suggestions, etc!

Topic revision: r48 - 11 Apr 2016, RichMorin
This site is powered by FoswikiCopyright © by the contributing authors. All material on this collaboration platform is the property of the contributing authors.
Ideas, requests, problems regarding CFCL Wiki? Send feedback