Content management, information governance, process writing
Technical Writing: What’s your view
I have over 23 years of experience as a technical writer. My enthusiasm to deliver clearly defined documentation/content strategy has never diminished. Yet, two common issues remain:
management expects a quick return on their budget, and
meeting people who think our role is a waste of time.
Our role is vital, and without us, standards of written and oral communications will forever diminish. Like many technical writers, I have various skills which overlap into different roles. I may operate under the title technical writer, but I have many more job titles under my belt.What skills do you ask? I communicate with many experts and produce relevant documents, namely policy and operational process documents, regarding maintaining a network. While I may not have the technical knowledge, I could step into a role and manage the infrastructure working with technical teams.
What can I tell you?
Despite the title, we are not technical experts.
we are documentation experts,
we have an innate ability to understand the technology and explain with help from an SME how it works,
We can analyse workflows and write complex processes with drawings to help teams work more efficiently,
our job is never straightforward as we rely on many factors that hinder progress,
A change to one document means changes to related documents that contain exact content,
writing is not easy:
Try writing 300 words about yourself. When done, look closer; how many errors can you see, and what changes will you make?
We work with people who are not technical writers.
And people who do not understand documentation but have an opinion on how to write and manage documentation.
We are not miracle workers:
If you expect to see results within a short period based on an issue that has continued unchecked for many years, you will be disappointed.
Many assume we do a cut and paste job and have no idea that writing and managing reams of content is a fundamental role. If not, companies would not need people like me to make sense of the problem, offer a solution, and complete the job.
What do we do?
I have worked with developers, engineers (of varying shades) and IT subject matter experts. The majority either
Regard documentation as a luxury
write their documentation, or
I do not see the point,
The developers I have met consider technical writing below their pay grade. If you think we are below your pay grade, you need to understand our role and responsibilities.What do we offer?We provide a link between the business and the users by describing the product’s potential.Knowledge management: if the knowledge resides in a team member’s head, get it out before that head moves on. That knowledge is an asset. A skilled communicator is essential to get this work done.We create critical information that is subject to an audit.
Writers can help with ITIL, security standards ISO27001 with quality, processes and procedures,
They can also help marketing teams with collaterals, white papers, marketing materials, etc.
They can create newsletters—internal and external.
Who cares? No one reads it!Try telling that to your customers who spend more time calling your helpdesk. If your documentation is not up to date and compatible with their version, you will hear the complaints loud and clear. There is also, in many cases, a clause contained in the Ts & Cs that explicitly makes clear the business will provide documentation.Relax at work!We don’t get much time to relax because we’re always looking at ways to improve the documentation quality. It is not a standstill role. As colleagues overlook us in many stages of the development, the release phase can be daunting due to:
Last-minute functionality changes,
managing un-realistic situations,
Multitasking—working on other vital projects.
There is a high level of stress factor involved in this profession due to uncommunicative team members and unrealistic expectations whereby managers expect the documentation to be ready and available within a few hours. Sorry, unless you have a mega team of technical writers, that will never happen.Documentation review can wait. If that is the case, you must make documentation an integral part of the software development life cycle (SDLC). It will help to:
Include the documentation review in the schedules of the reviewers,
return review comments to writers on time,
Writers are aware of necessary changes in advance of deadlines to make the required modifications.
People assume technical writers only write and think it’s an easy job. The importance of technical writing will come when they understand the following:
The actual work a technical writer does,
we utilise other essential skills,
the management of multiple issues to enable the completion of a project,
the process of documentation is also a process of quality control.
Be aware of your technical writer(s) and what they do to make you look good.Do technical writers work?A technical writer performs many other tasks and related activities as a part of the documentation process:
Multitask: work on multiple projects at different stages of completion,
Organise: keep projects to prioritise the work,
Be patient: deal with deadlines,
Manage: track multiple documents and content,
Training: train staff in communication and writing skills.
An SME can do the job just as wellThat is debatable:
An SME rarely has time to produce the documentation and has other priorities,
your SME may be a good writer, but that does not an excellent technical writer make,
they leave gaps in the content because they don’t think it is worth a mention.
If so, a technical writer will revisit the documentation and test for gaps and add the missing content,
professional technical writers are:
produce high-quality documentation,
structure documents for consistency,
design easy to use information, and
perform other related writing activities.
My advice, take technical writers seriously, and everyone will be happy.