How not to write a technical blog

As a software developer, my primary resource when looking for technical knowledge is the internet. Whether searching for tutorials on using an unfamiliar framework, consulting documentation for an obscure feature of a well-known language, or looking for existing design solutions to a new problem, my first instinct is to load up my preferred search engine and start punching in key search terms. In general this is a good strategy. While there is immense value in technical literature, a book is not the best place to keep reams of interface documentation. Nor, crucially, can a published author ever expect to keep pace with an early adopter using their blog to discuss a new open source library. New technology often suffers from a dearth of documentation, and the technical blogger is well placed to step in and fill the gap.

However, there are a number of substantial drawbacks in relying on self-published guides online. Firstly, fresh new content is crowded out by stale, outdated guides, suffering in search engine ranking next to established and hence more visited articles. This can be somewhat mitigated by appending the current year to the end of the search terms used, but distinguishing recent discourse from relevant content remains difficult. A second, related problem, is around the type of content returned, and the relative merits between the different formats. Blog posts, forum discussions, community-answered questions, published articles and official documentation all exist within the same space while targeting different audiences, and it takes experience and knowledge to know which sites to trawl for which purpose.

These problems, whilst frustrating, are not insurmountable. What cannot be easily overcome is the low quality of much of the content available online, both in terms of accuracy and technical rigour, and also the clarity and articulacy with which it is written.

It should come as no surprise to anyone working in this industry that writing clearly about software is difficult. As a relatively young discipline, software suffers from a deluge of technical jargon, which provides conciseness to the expert but mere obfuscation to the layman. In a broad and fast-changing field, we are all laymen outside our area of expertise, and since programming skill is enhanced by a broad technical palate, those developers who wish to achieve mastery of their field are required to learn an inordinately wide lexicon of technical terms to advance. Worse still, these terms are often used interchangeably and with different meanings in different contexts. Acronyms abound, compiler keywords permeate language and confusion reigns.

Greatly compounding this situation in many blogs is a lack of focus on writing quality. Muddled or incomplete descriptions of contextual software are often followed by incomplete explanations of the new feature being discussed. Code examples are frequently given with scant regard to illustrating intent, rendering them useless if a subsequent release invalidates the syntax. Points are ambiguously made, and often much of the philosophical discussion as to why an approach was taken is left out entirely, to be discussed and answered below the line by perplexed readers in the comments section.

The argument goes that much of what is written about software comes from the keyboards of developers whose skills lie in writing code rather than prose. Therefore we should be unsurprised that the clarity of technical writing is often poor, but disregard this as long as the content is useful. I find this viewpoint difficult to sustain.

Good software development is at core about producing code which is both a working solution to the problem at hand, and capable of being understood by the next developer who has to use, update or support it. The latter of these requirements is entirely about communication, and if you are to be a good developer then you must be capable of documenting your software in a precise, lucid and understandable way. If you are not capable of doing this for your documentation, how can you ever expect your code to meet the same standard? If this is expected of documentation, then it follows that published, written discourse should at the very least clear the same hurdles.

Writing well about software is difficult. It needs time, consideration and discipline, but the return on investment is to raise the discussion of high quality software to the same level. Hastily-written articles about technical subjects may quickly provide useful knowledge to developers researching an unfamiliar topic. But without clear description of the concepts involved, with an over-reliance on jargon or with ambiguity in explanation, ultimately they lower the intellectual level at which software can be discussed and understood.