Technical Writing connects the dots for your customer...
In times past, technical writing has been deemed a nuisance, an afterthought for many engineering teams as they drive their code through QA under enormous pressure and out into production. The subsequent rise of technical writing has been one of necessity, yet adoption has been slow considering the ramifications of not embracing it by widening a team's skill profile to include a technical writer. Let's face it, software developers don't have the time or the willingness to embrace technical writing as a primary task. Project and product managers have the process knowledge as they understand it from software developers, yet may lack the skills of a technical writer to create, review/refine and push to a production-based platform a technical document for the customer. Bearing in mind our customer user experience is a revenue affecting priority, what can a technical writer bring to the team that bridges the knowledge gap between the customer and the product?
Convention - For starters, a good technical writer will know commercial 'styles' of such a the Chicago Manual of Style are great aides for in-house conventions by their employer and thus simplify what goes where in a technical document. Whilst the presentation of documents to the customer becomes somewhat uniform, it all becomes redundant if the technical repository upwards is made on an ad-hoc basis. Those companies who do not implement an industry-wide convention like Darwin Information Typing Architecture (DITA) may likely lose information access ease, version control, and extendability of their repository for their customer, and/or internal users alike. Standardisation of what and where people can access knowledge regarding your product is key to achieving end-user operating competency, and satisfaction with the product.
Use Case Adoption - Software Developers by far are the most expert in the composition and process flow of the product they work on, but can often be poor technical writers for the same reason. They often lack the understanding of being in the customer's shoes operating the product, which can lead to serious oversights in technical process flows in their documentation based on what they think a customer knows and does not know. It's too easy to raise the bar to the standard of an engineer, when engineers may not use the documentation.
Silos - Company culture may be somewhat hierarchical in nature and technical documentation tasking often gets offloaded by a software development team to other teams notably marketing, product management or even a PMO function. This creates an incomplete knowledge transfer to professionals in other areas, who do not possess the technical understanding of the process flows, nor be able to identify the gaps that need to be filled upon the initial knowledge transfer. Like a DevOps Engineer, who bridges the gap between development and operations, a good technical writer can bridge the gap between business needs such as the target market for the documentation and the technical process flows. The technical writer will also be versed in creating technical documentation in a manner that is version controlled, auditable, easy to access and easy to understand for the end-user.
Software Development, DevOps and/or Operations teams who use a technical writer will achieve a more credible technical documentation source for their target market, which will increase customer/end-user satisfaction. By adopting technical writing into your development teams, you increase your product effectiveness and associated returns, which can only be described as a win-win for you, your customer and your product's overall success.
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!