Welcome to the world of technical documentation, where the language feels like embarking on a quest for the Holy Grail. But fear not, fellow adventurers! With a dash of humour and a sprinkle of wit, let’s delve into the whimsical realm of enhancing accessibility in these oh-so-serious documents. First things first, let’s talk language. Ah, yes, the tangled web of jargon and acronyms. It’s like trying to decipher ancient hieroglyphs without a Rosetta Stone. So, here’s a radical idea: let’s ditch the mumbo-jumbo and speak in plain old English! Novel concept, right? How about formats? Forget your ..read more

The chaos of Technical Documentation Management: A guide to saving your sanity The document management system is challenging to manage. Documents are in, out, changed, deleted, and archived. The document controller ensures everything runs smoothly, occasionally cracks the whip, and waves a baton. It’s like conducting an orchestra: keeping the music flowing in tune to Wagner’s – Ride of The Valkyries. Expectations vs. Reality: The Grand Illusion Technical documentation can be challenging to manage. Documents must be well-tagged, searchable, and updated without straining muscle. However, they ha ..read more

In my opinion As a technical author, I often hear the phrase “in my opinion”. What that means is a colleague doesn’t trust your judgement and thinks they know better. Some skilled engineers and project managers told me they understand technical authoring better than I do. They consider their documents through rose-coloured spectacles as ‘Good’, leading to a difference in the definition of’ good’. They avoid asking me to review it, but when the boss notices discrepancies, he asks for a second opinion. Cue me and my trained eye.  After I completed the editing, the document author found his ..read more

What does good look like?  How do we establish a shared understanding and define what ‘Good’ looks like for presenting information in an organisation? Everyone has a different opinion. If we cannot apply what good looks like, it results in problems in writing and preparing technical documents.  The question touches on a common scenario in the tech industry. We have individuals or teams writing technical documentation. They shun our expertise because they want to look good. This approach leads to mixed outcomes when the document writer needs more skills. So, what does good look like ..read more

A hiring manager asked about the significance of technical authors in a project. He had hired someone to write the project’s documentation. Unfortunately, the final document did not meet expectations. The hiring manager had hoped that the documentation would provide answers to questions. However, the writer produced a document without consulting subject matter experts (SMEs). As a result, the document failed to meet expectations.  The issue: Leaders don’t understand what we do. Here are some critical aspects of his dilemma:  Recognising the Mistake: The manager acknowledged not hirin ..read more

IT Audits IT Audits: A technical author’s view from the front line. I have worked on several projects, including an audit of a company’s IT ahead of a migration from one data centre to another. In three cases, no documentation existed; in the fourth, documentation was scattered around in various places. Data Centre migrations An IT audit focusing on a data centre migration project aims to ensure the process is well-planned and executed to minimise risks, guarantee operations and data integrity continuity, and adhere to relevant standards and regulations. This article introduces the data centre ..read more

In the world of technology, unsung heroes lurk in the shadows, wielding their pens (or keyboards) to document the wonders of code, hardware, and software. In my case, training materials, editorial and consulting. Yes, we’re talking about technical authors – the wizards of words, the maestros of manuals, and the unsung champions of clarity in a sea of tech jargon. Contrary to popular belief, technical authors have a fun job that goes beyond just following rules. So, buckle up and prepare to embark on a journey into the quirky world of technical authorship! First, let’s debunk the myth that tech ..read more

Technical authors should prioritise learning how to plan their documentation projects. Project managers underestimate the complexity of such projects, leading to negative consequences for their success. Consulting professionals for advice is crucial to avoid setting unrealistic timelines and targets. Documenting anything takes longer than project managers realise. They often prioritise other aspects of the project over documentation, leading to inadequate planning for documentation efforts. Project managers must plan and execute documentation projects more efficiently to achieve goals. Clear c ..read more

It is not unusual to find companies still use Shared Drives to store their documentation. As many Technical Writers will point out, the problem with shared drives is that they are neither secure nor searchable. What is the problem with shared drives? The folder structure has too many levels meaning documents are difficult to find Information gaps exist as users keep copies of documentation locally and not on the shared drive. There is no formal ownership of the documents. The title and subject of the Document do not accurately reflect the content. Admin has not set up Document versi ..read more

How many technical writers like me receive calls from agencies trying to source a content writer? It is not uncommon as many writing jobs these days appear under the banner of Content Writer. If you want to choose a suitable writer, read on. One day, I had to explain the difference between our two titles—comparing my technical authoring skill set to that of a content writer. Would you know the differences between a content writer and a technical author? If you get it wrong, it will be a costly mistake. So, what do you know about the following job titles? Technical writer Documentation manager ..read more