21 Jan 2015
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.
23 Dec 2014
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.
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!
17 Oct 2014
So you can now publish the docs for your Elixir package with
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
$ mix hex.config key
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_KEY with the output we got above (minus the quotes):
2. Configuring Travis to do our job
Finally, we have to modify
.travis.yml and add an
- wget http://s3.hex.pm/builds/elixir/v1.0.0.zip
- unzip -d elixir v1.0.0.zip
- export PATH=`pwd`/elixir/bin:$PATH
- mix local.hex --force
- mix deps.get
script: mix test
- 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
Docs successfully generated.
View them at "docs/index.html".
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.