Documentation is really ugly! WTH is up with that?
As a new developer, I spend a lot of time reading documentation. As a designer, most of it makes me want to gouge my eyes out. I can’t help but look at things before I read them. And almost all the documentation I come across, whether it’s for languages, libraries, gems, or APIs, is really ugly.
What is this documentation thing, anyway? Where does it come from?
Before I started researching for this post, I thought that documentation was lovingly written by developers after they’d finished their code. “I’m done with my masterpiece, now time to go through and explain exactly how it works!” Apparently that’s not always how it happens.
Documentation can be automatically generated from the comments in code, using a program called a documentation generator. Ruby’s documentation generator is called Rdoc. Rdoc’s website says: “[Rdoc] Generates structured HTML documentation from Ruby source. Automatically extracts class, module, method, and attribute definitions. These can be annonated using inline comments.”
Cool! How handy. But…
The main point of documentation is to make your code easy to understand, right? Often times the language is difficult and confusing, especially for beginners. Also, is anyone thinking about how this automatically-generated content looks?
A hot-or-not of documentation websites we’ve used:
Let’s look at some NOT’s:
Now the HOT’s:
Erin made this website to walk through the concept of Model, View, Controller architecture:
Well? What would YOU rather read?
What is the solution?
The documentation websites I’ve come across so far have some common design issues.
2) Lack of white space
3) Typography: line-length, leading.
Readers are presented with an impenetrable wall of text: Line-length all the way across the page, and no whitespace.
I’m working on a custom stylesheet that will rectify some of the common typography problems in documentation websites.
Or, developers can use one of these documentation generators that consider design in their output:
Make code accessible for all
We’re in the midst of a movement to make code more accessible for all. I think that a lot can be accomplished towards that goal by making documentation more legible, even beautiful.