We've been successfully writing our technical documentation the same way for the past 35 years, we are a NASDAQ listed organisation with profit and growth year on year, our model works, we are perfect, we are not changing, .....; f**k you and your new fangled ideas and fads

Some online technical documentation, and from leading software vendors, is atrocious; old-school railroad diagrams, pages and pages of drivel, and lacking in example code or API usage excerpts.

Firstly, some praise, and where it’s due.

• Take a peek at the Faircom c-treeACE SQL reference documentation. What more could you want? It is a textbook example of how to write technical documentation. Numerous examples, the documentation is written clearly, and there is a general look and feel that it has all been handcrafted rather than shoehorned into a corporate document template that was first defined 35 years ago [and I didn’t pluck that number out of the air – I have used the occasional Faircom product since the early 80’s, since Micro B+ (I discovered an OCR/scanned rendition of the original technical reference manual here – the nostalgia is settling in) and Access Manager, and the documentation for these products and c-treeACE are incomparable]. This reference material, also shipped in paperback when you purchase c-treeACE, is likely to meet UX expectations using almost any selection criteria you choose to define.
•  The current Microsoft technical documentation for the C# programming language even allows for user contribution and feedback. It is such a pleasure to visit and read this quality technical documentation; the language used is targeted at an appropriate level, there are coding examples to compliment the technical specifications, and so on. On top of this, you can always quickly find the information you seek, either on the Microsoft website, or by using a search engine.
• How about PostgreSQL? It feels like such a quality product, the online documentation is superb too, occasionally splashing out with a bit of colour. Ballyhoo! A few moments ago I found myself reading-up on PostgreSQL window functions (Analytic Functions in Oracle speak). The online documentation here even asks for feedback for the purposes of product improvement.

None of the documentation examples above has the feeling that it was written by some lethargic non-responsive dinosaur organisation comfortably sitting behind their cash cow product providing static templated reference content with an aloof view that “we’ve been successfully writing our technical documentation the same way for the past 35 years, we are a NASDAQ listed organisation with profit and growth year on year, our model works, we are perfect, we are not changing, our client base understands our documentation (and licencing and support) model despite competitors (and the rest of the world) adopting a more agile and modern approach; f**k you and your new fangled ideas and fads“. That comment is written in a very colloquial manner, but I don’t think it’s too far from the truth, and the offenders are some multinationals and they are holding back software development and progress effectively wasting developer/company time by not providing adequate documentation for their flagship products. Faircom have been around for ca. 35 years and their documentation and product quality has always been superb; other organisations of a similar vintage must look on with envy!

Given the choice, and regardless of my skillset, age, and experience, I am finding that my viewpoint for selecting technology is changing. When choosing a new implementation technology, I now also value highly the general readability of the underlying technical documentation giving it a proportionate score weight for technology selection. After all, this is what I have to use in day-on-day in software development, and there is a direct relationship to the technical documentation and my productivity. If the technical documentation lacks quality, that is a (big) contributing factor for me to abandon a product, despite the pedigree and prestige of the vendor. I don’t think this is an unsound viewpoint. I advocate that the quality and readability of the technical documentation should be included in the normal Carroll Diagram selection/exclusion criteria used to justify the business case for adopting a technology; choosing a technology vendor has to be more than just product feature-set,  licencing costs, and (perceived) vendor reputation! In terms of overall technical quality, all of Microsoft .NET, Faircom, and PostgreSQL and some unnamed others pass my selection criteria, and with flying colours! Some big-name multinationals and their flagship products do not pass the selection criteria – their product technical documentation has the same stale templated look decade upon decade, and it wasn’t even good two decades ago.

— Published by Mike, 08:41:01 17 August 2017 (GMT)