Why documentation is copywriting (for hackers)

Status quo

Okay Ruby, so we have to talk. Since even Jeff Atwood is proclaiming that you are measuring up nicely we really have to … about documentation.

Talking about documentation is not nearly as popular in the Ruby community as it is to talk about testing. Besides Loren Segal, who still tries to convince everybody to document their code (and seems to be the only one giving talks about it) there only seems to be Steve Klabnik, on his quest to document ruby-core.

But testing & writing proper documentation share some characteristics and I firmly believe that documentation is too often neglegted, just because it does not have the same direct satisfaction that extensive testing and coverage numbers provide.

Of course there are the advocates that do not get tired to emphasize Ruby’s beauty by proclaiming that “code is the best documentation” (DHH seems to be of them, but more on that in a second).

And then there are those folks who seemingly annotate every to_s and User#name method with a redundant comment (maybe to achieve “100% documentation coverage”). But, just like in testing, there must be a middleground here, because code metrics (and “fully documented” is a kind of metric) are always a two-sided sword. They are a great servant, but tend to be a cruel master, so to speak.

The trick is to use code metrics to your advantage, while providing documentation for the other coder’s benefit. Because having some documentation is a lot like having a guide in a foreign city: If he is good, it’s good. If he isn’t, it’s often better than nothing.

While DHH may not see the benefit of documenting code, he certainly has provided a good write-up of the malpractices often encountered in testing. Here we find the common ground: Don’t let the rules and tools dictate your coding style. The same applies to documenting what you have done.

So, inspired by David’s “Seven don’ts of testing”, here you go:

Do’s and Don’ts of documentation

1. Provide a README. Seriously, I can’t stress this one enough. GitHub can even populate new repos with one.

2. Don’t aim for 100% coverage in your docs.

3. You’re probably doing it wrong if documenting is taking more time than testing and coding.

4. Reserve namespace documentation for classes and modules that really shape your code.

    # ... extensive description ...
    module ImportantMixin
      module ClassMethods
   
      end
    end
   

Don’t add “The ClassMethods module holds the methods another module is extended with”. Annotating ImportantMixin::ClassMethods when you already described what ImportantMixin does is just documentation bloat (read: don’t document things that are implicitly explained).

1. Don’t document standard methods with descriptive names, unless you have a good reason. Never do this:

    # Returns a +String+ that inspects the object
    def inspect
      "<##{class.to_s} ...>"
    end
   

2. Attempt to document your code when you’re satisfied with it from a coding-point-of-view. If it is not self-explainatory, try explaining it to 6-months-in-the-future You (or a five-year-old).

Think of it as copywriting

Documentation should be an added layer of clarification, where the code can’t speak for itself. This is why documentation is more often than not interface copywriting; just not for the end-user, but a fellow coder.

Afterthought regarding Rails:

Don’t force yourself to document every controller, model, and helper.

# Handles creation, management, and deletion of +User+ objects
class UsersController < ApplicationController

end

Seriously. See points 4 and 5.

TL;DR Document your code; just not for the sake of documenting it.