Keeping up with the younger Crowd

One of the best things about technical writing is the variety it offers: who you work with; the style of writing required; the type of products you document; your input into and impact upon the products themselves; the medium you use, and so on. One of the products I work on is highly technical, and the documentation is funky that way too. The product is Crowd. If you find authentication, authorisation, single sign-on and user management sexy, then Crowd is for you. And the documentation would be your choice of bed-time reading.

This week we released Crowd 1.2, a major release with lots of new features. So we published many new and revised documents too.

Documenting this type of product is interesting. On the one hand, you get a kind of glow from belonging to the elite group of people who understand words like ‘Acegi’ and ‘OpenId’. You have the chance to indulge your natural inclination for long words and other esoterica. You may notice one or two creeping into this blog post 😉 On the other hand, in the documents themselves the trick is to know when to explain something and when not. After all, we have a savvy readership. I try to keep explanations short. Often all you need is a link to an authoritative website and an expansion of an acronym on first use.

Gourmet’s guide to a technical document: Mix the dry ingredients. Sprinkle in the acronyms. Pour the open source over the top.

Another interesting thing about this type of documentation is that the developers write much of the content themselves. As technical writer, I guide and tweak the content. When I can, I’m keen to jump in and test-drive the integrations myself before documenting them. But sometimes that’s not practical or efficient.

Wikis are great for collaborating like this. I might kick off a document by creating the skeleton structure. Then the developer writes the first draft. I jump in and tweak some things. The development lead and another technical writer do an in-depth review. And there you have it, a document to suit the epicurean taste.
Sometimes, you can even make the document look pretty:

Ain’t that just copacetic?

Have you noticed that your brain starts shooting off at a tangent when you’re writing dry technical kind of stuff? I had to explain ‘Acegi’ in the Crowd release notes:

Crowd 1.2 provides a built-in application connector for Acegi, a security solution with a particular emphasis on Spring Java/JEE applications.

Here’s what my gray matter kept insisting was relevant:

Spring has sprung, da grass is riz

I wonder where da boidies iz

Da boidies is on da wing

Don’t be absoid

Da wings is on da boid

That’s a jingle that my dad recited to me when I was just a kid. It’s spoken with a cockney or Bronx accent. Evidently the verse’s origins are obscure, though it’s often quoted, and sometimes cited as an anonymous work called ‘The Budding Bronx’. Isn’t it weird how such things stick in your head? A blog is a great place to get rid of such insistent promptings from the subconscious. The jingle would probably, though not indubitably, be considered out of place in the Crowd docs.