Technical writing - my first ten years

Posts on the @LunatechLabs tech blog, 2005-2014 2021-03-02 #writing

People sometimes ask me about starting a public tech blog, to give developers an opportunity to write in public, and promote their work. The recently-resurrected Lunatech Blog shows how I did this, from 2005 to 2014. I started regular blog posts in my first year at Lunatech, which had no other online content marketing at the time.

I produced Lunatech’s blog by example, writing about half of the (roughly) twice-monthly posts myself. I wrote about a variety of topics: technical articles for developers, agile software development, reviews, and company events. At the time I didn’t worry much about which topics to choose, although analytics data gradually revealed that niche technical topics had the most long-term traffic.

2005

Looking back to 2005, I like the one about information radiators the most, because I found it so satisfying to update the chart every day. Of course, the chocolate cocktails also delivered plenty of satisfaction.

From a technical writing perspective, the articles about web application user interfaces make me cringe now, because they say so little. At the time, I had just started exploring the idea of writing about technical topics, and remember that using How does this work? as a prompt, helped me start writing. The post about URLs in Struts (a then-popular Java web framework) generated the most traffic, illustrating that articles that solve a real and recognisable problem have more value that merely describing things.

2006

In 2006, I tried two new things: book reviews and a customer project summary. Although I expect more readers found the books for software developers article useful, I still really like the think piece Wiki is my word-processor, which I’ve thought about re-writing several times. Now that we no longer use wikis, I would probably title that Notion ate my wiki today.

I improved the tech blog in year 2 by building on the previous year’s web framework article success, with follow-up Struts tutorial articles. Meanwhile, the bullet lists article shows that I had started thinking more deliberately about technical writing.

2007

2007 started with another think piece about business class, based on a conference presentation I’d seen at JavaPolis: I don’t like the blog post much, but its insight still resonates. Meanwhile, I started translating user group events (marketing budget spent on beer) into blog posts, and writing more tutorials. My favourite article of the year remains the technical writing tutorial on how to write user-interface instructions.

2008

2008 continued previous themes: mostly company events, a review and a tutorial. Fortunately, I still found space for a more quirky articles, in How to draw lolcats and The programmer’s private office, both disguised think pieces.

2009

In 2009, I returned to more serious technical tutorials, to write about JBoss Seam, our new favourite Java web framework at the time. I don’t remember why I wrote fewer posts in 2009 than in other years, although spending half the year commuting to a customer’s office in, might have cost me the time I might have spent writing. At least I had time for another cocktail recipe.

2010

The blog changed in 2010: I doubled my writing output, writing many more tutorials. I also started to look at new kinds of articles, finding new topics in recruitment, and conference attendance tips.

A new Java web framework drove this change, as I became a committer on the Play framework, to edit and write its documentation. Writing on another ‘project’, five years after starting this tech blog, changed a lot about my experience of technical writing.

2011

I wrote even more blog posts in 2011, mostly as a result of writing companion articles to other activities, and experimenting with web framework documentation ideas. Having decided that volume counts, this increase came from more systematically asking can I blog about this? Today, the comparison of Scala, Ceylon and Kotlin language goals still resonates the most with me from 2011’s articles, not least because I wrote my first Kotlin code only two months ago.

2011 also featured another technical writing escalation: I started co-writing a book with two Lunatech colleagues that would take two years to complete. This book - Play for Scala - taught us a lot about technical writing that helps people get things done, and improved how I approached tutorials.

2012

Developer conference presentations dominated my year in 2012. I also wrote my first agile software development experience report, the first of several articles about Scrum, while in an interim Scrum master role on-site at a customer. By this time I had become used to the idea that I should write about my current work, even if I would prefer to write about other topics.

2013

2013 saw fewer blog posts, presumably as a result of working on finishing our book. After that, I applied what I had learned about writing tutorials to a new series about early versions of Slick, a database access library.

These Slick tutorials explored a new technical writing constraint: no forward references. I’d seen that in the book Atomic Scala, as a way to make the book easier on readers.

2014

I kept up the writing pace at the start of 2014, with two posts per month at the start of the year. Most intriguingly, I wrote about remote working, eleven months before I would start permanently working from home (and have ever since).

I didn’t write any new topics in the months before I left Lunatech, at the end of June 2014, hence the series of retrospectives. I did write a lot after that, though. I left Lunatech for a six-month sabbatical in London, where I started this personal blog with a vengeance, writing 31 posts in the first two months. 😀

Writing by Peter Hilton