Blog

Technical Writing on Projects

Technical Writing on Projects

Why technical writing on  projects cannot be overlooked

Do you wonder why Confluence document repositories always have gaps, partly drafted documents that never seem to be kept up to date? If you do, you are not alone. The fact is that technical writers are too often sourced to the creation and curation of customer-facing documentation only. It is an industry-wide problem. As anybody with experience in technical projects will tell you, the focus of existing technical writing resources is not there for internal documentation, leaving the specialist burden to engineers, product owners and sometimes project managers to create technical documentation. Document repository curation often falls to the related function post creation who is not equipped to carry out the task to a defined standard with any degree of consistency over time.

So, if we get by, then why bother looking at it all? One could say that life goes and it's a shrewd decision by management to not employ a technical writer(s). It can be said that they are thus getting the most out of the technical team over time? In reality, it's a gamble and all circumstance related. The upside to the management decision is heavily dependant on an engineer(s), who has a talent for and skill in technical writing to create and curate the content over time. There are downsides, which make up a justification for hiring a technical writer to round out a team's output, which I see as follows:

1) Engineers are not writers by skill or base ability, as the conveyance of information as knowledge is a skill in itself. Engineers often under time pressure struggle with competent technical writing leading to lower quality outputs despite knowing the software and/or system at a very deep level. These over the course of time lead to misunderstandings via new staff reviews of them. If the technical readers are not experienced enough, the resulting actions may lead to production impacting errors.

2) Incompleteness and gaps in the likes of how-to documents and runbooks cause ad-hoc solutions to be driven where engineers have to just figure it out. This requires engaging with more experienced colleagues and getting ad-hoc training on the task, which solves the immediate problem. However, the lack of documentation and curation thereof leads to wider colleague re-engagement by case repeating itself over time, which is a bias error in resource allocation.

3) These knowledge gaps found in documentation also elevate the risk of a technical mistake and reduce the overall performance levels of highly-skilled engineers in support of new colleagues, who may have production-level resources to care for along with expert participation in multiple projects. Over the longer term, tribal knowledge around projects, products and processes increase in technical teams and often walks out the door with experienced engineers heading to the new role. The resulting risk posed to the company in terms of knowledge gaps in key areas increases according to the decreasing number of remaining members in the tribal knowledge circle until there are none remaining. 

3) Engineering teams add value over the longer term with skills developing know-how, processes and procedures with extendable functionality and scalability in mind. The same can be said for the skills and processes around technical writing to standards, consistency in object creation and extendability. It is all done and stored in a manner that is scalable, designed to be reusable and with version control can be auditable. This approach creates a centre of expertise that hones the company's ability to turn information into knowledge and deliver it to the reader in a digestible format without the need to allocate further resources in the delivery of technical knowledge around a task and/or topic.

Having a central repository of knowledge covering defined areas at defined levels of complexity, which is easy to navigate at speed is a key asset to the technical internal success of a technical organisation in the company. For the overall success of the company, having the ability to keep the lights on in regards to its technical projects and systems relies on it and deserves investment in its development. 

Stay tuned for more on Writing in this blog along with articles on other areas of interest in the Infrastructure 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!

Best Regards

John

 

Related Articles

Image of Jenkins workflow

CICD and Jenkins

Azure DevOps VNet Topology image on Azure portal.

Azure V-Net Demo

DevOps