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.