Writing Code and Writing About Code 6/10

One of the most exciting parts of my role back at Liferay was to create code samples to accompany documentation. Because the platform is open source and so customizable, a lot of the docs describe low-level code. If you've been accompanying this series from the beginning, you know that I love to code and was initially trying to get a job as a software developer. It's pretty incredible that I still get to write code even if not as a developer.

Part of the Liferay Learn style was to include a working module for the reader to test the feature the docs describe. This meant that whenever I wrote about Hibernate queries, dependency injection, declarative services, service wrappers, servlet filters or really any piece of Liferay's architecture, I put my back-end development knowledge to use.

Over my time at Liferay, I got to write dozens of OSGi modules describing all sorts of concepts in modular architecture. It's been a great way to bridge writing and engineering, while ensuring the docs demonstrated the product they taught.

For an example of how these code samples were integrated with the docs, read Advanced Queries. It was a series of docs I wrote about different ways to connect to the database. All of them include working code samples also written by me.

It's funny how people sometimes forget about the word "technical" in "technical writing". Most people who work in the area are English majors or journalists who struggle to find work in the areas they actually wanted and find this to be the only job where they can put their writing skills to use. But some of us are from the other end. Being an engineer who communicates effectively is a solid way to guarantee quality documentation.

I'd definitely encourage other engineers to practice writing and communicating more clearly. The bridge between the two worlds is a lot smaller than it seems. What is programming if not explaining complex problems in a language the computer can understand? And what is documentation if not explaining complex problems in a language the end user can understand? Technical writing is really just a different type of translation. While we might all be speaking English, that doesn't mean we're speaking the same language. And translators are usually expected to be bidirectional, so knowing how to code is a big plus.

I'll admit I've been lacking a bit in the programming department. If it weren't for these code samples, I would probably not be coding at all despite how much I love doing it. From now, I'm going to put some more effort into my personal projects. But, whatever happens next, I hope my job always has room for me to get my hands dirty.