trivelop   home of @rrrene   –  

Five ways to improve your Elixir docs

Here we go: Five not-so-technical tips to improve your documentation quality:

1. Docs are copywriting for hackers

Documentation should be an added layer of clarification, where the code can't speak for itself or is too far removed from where it is being utilized. This is why documentation is often interface copywriting; just not for the end-user, but your fellow coder.

2. Give copy-n-paste usage examples

People like fiddling around with code. IEX makes it super easy to see what your module/function does given input A and how that changes given input B. So provide some concise examples, so people can have some copypasta.

3. Keep it concise

Apropos concise: You can help people by writing in a concise manner as well. "Explain it to me like I'm five years old" is not the worst sentiment when writing docs. Alternatively, think "How can I describe this to my future self, who has not seen this code in a year?".

4. Only document public interfaces

This is kind of a given, but consider the implication: Think about what functions are public and which are private in terms of reading a documentation of your own code. Sometimes you discover that you have to refactor things just because the docs don't "read right" for how things are.

5. Keep it easily updatable

Your code changes, some parts churn more than others. Documentation has to be kept up-to-date as well, but you can mitigate the need for constant docs-updating by writing what the method/module is used for rather than describing what it does in nitty gritty detail. This way, you don't have to update the docs for every small refactoring.

Happy Holidays (and HTTPS)!

Before going into Holiday Hibernation Mode, I wanted to say Thank You!

Inch, my little hobby project to raise awareness for the importance of inline code documentation, had a wonderful first year and Inch CI, the complementary CI service started in June, has had a superb first sesaon and is now serving badges for over 500 open source projects on a day-to-day basis.

Inline docs I am secure! :)

Last week, HTTPS was enabled after the issue came up on GitHub and I maintain a todo-list of things that I want to work on in 2015 whenever I find the time (better GitHub integration, additional languages, new design, ...).

This would not have been possible without the encouragement, feedback and kind words from the open source community. To all participants, contributors and constructive critics of this project: Happy holidays and thanks a million!

Continous Documentation of Elixir packages with Hex and Travis CI

So you can now publish the docs for your Elixir package with

$ mix hex.docs

That's it. That is crazy simple. One command and they are online. But we can make it even simpler: Let's delegate the publishing duties to Travis CI.

There are two things we have to do for that: Configure our Hex account in the Travis build and advise Travis to publish our docs for us.

The rest of the post assumes you have published docs for a Hex package before. If you haven't, please read this introduction.

1. Putting your Hex credentials into Travis

First, we have to retrieve the information we want to put into our Travis builds:

$ mix hex.config username
"rrrene"

$ mix hex.config key
"3J98t1WpEZ73CNmQviecrnyiWrnqRhWy"

These are our username and password for interacting with Hex. We will use these to tell Travis to publish our docs.

Next, we go to our repo's Travis page and into "Settings" and then click the tab "Environment Variables". Here, we add two variables: HEX_USERNAME and HEX_KEY with the output we got above (minus the quotes):

Inch CI

2. Configuring Travis to do our job

Finally, we have to modify .travis.yml and add an after_script: section:

language: erlang
otp_release:
  - 17.1
before_install:
  - wget http://s3.hex.pm/builds/elixir/v1.0.0.zip
  - unzip -d elixir v1.0.0.zip
before_script:
  - export PATH=`pwd`/elixir/bin:$PATH
  - mix local.hex --force
  - mix deps.get
script: mix test
after_script:
  - mix hex.config username $HEX_USERNAME
  - mix hex.config key $HEX_KEY
  - mix hex.docs

This publishes our docs with the username/key combination we configured, continously.

Using worker: worker-linux-10-2.bb.travis-ci.org:travis-linux-22

...

Generated inch_test.app
Docs successfully generated.
View them at "docs/index.html".
[#########################] 100%
Published docs for inch_test v0.0.1
Hosted at http://hexdocs.pm/inch_test/0.0.1/
Done. Your build exited with 0.

If you like, let's have a chat about this on Twitter.

Fork me on GitHub