Using Coltrane changes in documentation

In jazz, there’s a common method to get from one place in a progression to another. It’s called the two-five device (really it’s ii-V, but I want to convey that that it’s pronounced “two-five”). In music theory, the five chord wants to resolve to the one or the tonic, that is, the key that the song is in.

Coltrane found a way to get back to the tonic by using a series of ii-V devices that go up minor thirds. This method of moving around is called a Coltrane change. It sounds complicated, but just know: it’s a way to move around in a song and still get where the song needs to go. A Coltrane change is just a series of chord substitutions, and using substitutions is a common device used in jazz.

Coltrane changes remind me that no matter how well I design a documentation set, there are people who find things differently than I expect them to. I need to account for my readers by offering alternative ways to get to the content they want. They can use the TOC or an index. However, most readers won’t use these archaic methods. Most of my readers will be using search or links. So I try to give them richer links and better search metadata, the ii-V of documentation.

About scotmarvin

Scot is a content strategist for Oracle. He's a slacker and smartass involved in content design, content architecture, big data, cloud computing, and other buzzwords related to technical stuff. He loves his family, history books, jazz guitar, and the Minnesota Vikings. Scot is a proud father, so don't make the mistake of asking about his family unless you have four hours to listen to him ramble on about his kids.
This entry was posted in documentation. Bookmark the permalink.

2 Responses to Using Coltrane changes in documentation

  1. A very entertaining analogy, Scot. 😀

  2. scotmarvin says:

    Thank you. You’re very kind.

Leave a Reply

Fill in your details below or click an icon to log in: Logo

You are commenting using your account. Log Out /  Change )

Google photo

You are commenting using your Google account. Log Out /  Change )

Twitter picture

You are commenting using your Twitter account. Log Out /  Change )

Facebook photo

You are commenting using your Facebook account. Log Out /  Change )

Connecting to %s