Editing HowTo

Hack the Docs (HTD) is supposed to be educational, fun, and useful. Git(Hub) gotchas and Mix madness don't contribute to this, so let's take a simpler path.

Overview

  • Assemble an editing team (eg, 1-4).
  • Select and register a target module.
  • Improve the @doc for each function.
  • Submit changes; issue a pull request.
  • Savor your egoboo, fame, karma, etc.

Details

I'm extrapolating from similar experience at consulting gigs, hack sessions, etc. So, I've probably missed some issues and tricks. Let me know what you find out; I'll spread the word...

Assemble a team

Some of us like to work by ourselves; others like to work in teams. Up to four people can sit comfortably around a largish display. Achieving the same level of communication via electronic channels (eg, IRC, screen sharing, twitter) is typically a bit more challenging, so an online limit of two may be safer. That said, let us know what works for you!

Select your target

Our current focus is the Master branch of the Elixir Standard Library. Look over the ESL page, looking over the available modules (etc). Guided by your interests, technical level, and time budget, select one that needs love. Send me some email containing your contact information (eg, name, IRC handle); I'll fold it into the appropriate row and table on the ESL page.

The Bitwise module seems like a nice starting point for this exercise. It has no side-effects or external dependencies. It contains about a dozen macros, but they all look easy to explain and demonstrate.

Improve the docs

Inspect the online docs for the Master branch of the selected module. Is there an accessible and comprehensive introduction at the top? Is all of the terminology (eg, "bitwise") explained and/or linked to a reference? Is the text clearly written and easy to understand? If not, make a note to improve the @moduledoc entry.

Moving on to the individual functions, note which ones need improvement. A @doc entry should let the reader know what the function does, how to use it, and what to expect as results, side-effects, etc. Typically, this takes the form of a short paragraph and one or more examples.

The first entry in the Bitwise module (as of 2015.0212) clearly needed some love. The explanation wasn't particularly clear and there was no example at all. Based on the information below, would the typical user be comfortable using the &&& operator?

left &&& right

Bitwise and as operator.

Get a working copy

Click the Source (code) link just above the Summary section. Scroll to the top of the resulting page and click the Raw button. Copy all of the source code, then paste it into a local text editor. This will let you make your edits in a safe, familiar environment.

Edit some Markdown

OK, let's edit some Markdown! In your local editor, scroll down to the @doc entry for the &&& operator:

@doc """
Bitwise and as operator.
"""
defmacro left &&& right do ...

Adding a few words and some formatting, we can make the explanation clearer. In this case, a single example can cover all of the possible cases. Specifically, we can use a pair of numbers (eg, 9 and 3) that exercises all four combinations of bits (1/0, 0/0, 0/1, 1/1). Here's a plausible revision for the @doc entry:

@doc """
Infix operator; calculates the bitwise AND of its arguments.

    iex> 9 &&& 3
    1

"""
defmacro left &&& right do ...

Most of the Bitwise examples can use the same pair of numbers and a similar explanation. However, the arithmetic bitshift operators (bsl, bsr) require more explanation and input values that show off truncation and sign extension.

Preview the output

Preview the output formatting, using John Gruber's Dingus. Set the Results pulldown to Preview, paste in the contents of your @doc entry, and click Convert. You should see something like:

    Infix operator; calculates the bitwise AND of its arguments.

    iex> 9 &&& 3
    1
    

Rinse, repeat...

Edit and preview each @doc entry in the same manner, saving the results. Take another look at the @moduledoc entry: can you improve it, too?

Ask for feedback

At this point, it would be a Good Idea to ask for some feedback. Copy your collected entries to a public site (eg, pastie.org), post a link to the #elixir-lang IRC channel, and duck!

Push changes, etc.

Even though you think you're done, scan through everything one more time (amazing how many problems this can find... :-). If you are (still) happy with your changes, you can push them to GitHub.

First, make sure that you are logged in to GitHub, then navigate to the Bitwise module in the master branch:

To the right of the Raw, Blame, and History buttons, click the pencil (online editing) icon. GitHub may display a popup message something like the following; don't worry about it:

    Clicking this button will fork this project so you can edit the file.

For safety, save your edited text first into a local file (eg, bitwise.ex). Then, copy and paste the edited text into the Edit file tab of the resulting page, replacing everything that was there before. In the Propose file change section at the bottom of the page, enter some descriptive text, eg:

Hack The Docs contribution

Clarify and expand textual descriptions; add examples.

Click the Propose file change button, then click the Create pull request button. Congratulations, you're now a (potential) Elixir contributor!

Note: Here are the original and edited versions of the Bitwise module's source code (Elixir + Markdown).

Resources

Here are some useful web pages:


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: r6 - 04 Mar 2015, RichMorin
This site is powered by Foswiki Copyright © by the contributing authors. All material on this wiki is the property of the contributing authors.
Foswiki version v2.1.6, Release Foswiki-2.1.6, Plugin API version 2.4
Ideas, requests, problems regarding CFCL Wiki? Send us email