Documenting Conventions

By Simon St. Laurent
August 21, 2008

"Convention over configuration" is a great way to write code - but a lot harder to explain when it comes time to write documentation. With explicit configuration the stories of how a framework operates are obvious, if not interesting. With conventions, they're interesting, but not obvious.

Configuration files, whether they're infinite piles of XML, YAML, a custom format, or the Windows Registry, are really, well, boring. Tutorials definitely explain some of the more relevant parts, but then frequently leave the rest to reference. It's not just that reference and configuration are a good match in boring, but that configuration files are practically a perfect match for the detailed explanations of a reference section.

Over the last five years, more and more frameworks have become "opinionated", providing a default way of doing things that's specified in code rather than in a configuration file. When users share the opinions of the framework makers, it's great - things just work.

When users don't share those opinions there's a range of possibilities. Sometimes it's still possible to change, though generally done by writing new code rather than changing configuration settings. If it's too hard to change, of course, there's always the option of finding another framework.

Draft diagram of a Rails response
Draft diagram of a Rails response

There's another problem, though. "It just works" is great once you've learned the magic formula for making it work, but as projects move from prototypes toward final versions, there's a nasty tendency for things to grow more complicated, beyond the flexibility of the conventions. Even at the simplest stages, knowing what to change where to create a given result can be really difficult.

For Learning Rails (coming in November), I originally tried to show these things in action and explain them with prose along the way, but it became clearer and clearer that these things really need a diagram, or, maybe preferably, a video. There are lots of parts in an overall flow, and losing track of any given part creates an opportunity for readers to get lost when they apply the lessons to their own work. There's also no easy way to write a reference for them.

It's almost as if there needs to be yet another book - How Rails Works - which walks through the source code and explains what assumptions it makes. Unfortunately, while there might be a market for How Rails Works, there is a much larger audience of people who want to make Rails work for them, on their specific project, rather than exploring the entire framework at an abstract level. I'd love to read How Rails Works, but suspect that readers without an advanced background in Ruby would have a hard time keeping up, at least until some core patterns became clear.

Hopefully we managed to reach the right balance with figures and prose, and I'll probably do a video/screencast on how these conventions work at some point too. At a more abstract level, though, it's a surprise to see that a coding style that makes programming much easier can actually make documentation considerably more difficult!

You might also be interested in:

Popular Topics


Or, visit our complete archives.

Recommended for You

Got a Question?