Blog

Image of a runbook template header on Confluence for technical writing purposes

Effective Technical Documentation

Why Technical Teams need a Technical Writer

There is no doubt in my mind that company culture in technology companies is writing adverse when it comes to technical writing and effective documentation. I have seen it many times in the past where it's treated as an annoying add-on job for developers, project managers and engineers. There are many reasons why this is and many reasons why digital products require good documentation to be effective as enterprise-level products.

Good documentation drafting practices require technique, training and skill to develop. Many management solutions focus on the centralised technical writing team. This is where a writer gets a ticket to document a piece of software for a customer-facing documentation repository or maybe write a technical runbook for one or more process executions. Whatever it is, the purpose of the document can often get lost if the technical writer simply does not have the process knowledge to be effective in drafting a technical document. This is where team writers become very useful. If your use case is one where a large repository of documents is required to be created and curated let’s say for a technical operations team, the technical writer as a full-time teammate will bridge the gap between the technology and its reader. This information delivery efficacy in delivering know-how via a writer that has operational-level process knowledge is well-proven for those who implement an effective solution. This means giving the writer an assignment pool of teams and the paid time to get trained in the team’s modus operandi, their existing process infrastructure and what they are/will require new documentation for. The smaller the organization, the bigger the spread of teams a writer can be assigned to for this type of full-time engagement in the development and curation of technical documentation.

As for projects, the impulse to onboard a technical writer late in the project lifecycle just before or after a digital product goes live is a mistake. Project managers should get a technical writer on the team after the end of the development phase and get them trained in the project workflows for the new product. This allows the technical writer to gain process understanding in the documentation of each iteration of the product. This revision-based approach to documentation solidifies technical understanding for the writer, who in turn delivers this understanding to the reader via a consistent, reusable and version-controlled technical writing architecture.

Whilst there are standards like the open source DITA standard for technical writing, good operational practice can often be a matter of management opinion and company culture. Those who engage in professional technical writing practices will always seek to bring in the technical writer early in the project lifecycle. The reason for this is the recognition of the qualitative value in effective technical documentation as part of their digital product. Stay tuned for more on Cloud Infrastructure in this blog along with articles on other areas of interest in the Writing and DevOps arenas. To not miss out on any updates on my availability, tips on related areas or anything of interest to all, sign up for one of my newsletters in the footer of any page on Maolte. I look forward to us becoming pen pals!

 

Related Articles

image of a project timeline for a Maolte Technical Solutions Limited article on major incidents and digital migration

Major Incidents and Digital Migrations

Image of Jenkins workflow

CICD and Jenkins

Image of AWS DR map and Azure Backup and Recovery Services Console

Disaster Recovery of Digital Resources