Technical Writing: What’s your view

I have been a technical writer for 23 years. I know my role as a technical writer. However, management can undermine my enthusiasm to deliver a clearly defined strategy due to their lack of knowledge and expectations.

It isn’t a new problem, and despite several attempts to address the problem through LinkedIn and my website, two common issues continue.

      • Management expects a quick return on its budget. and
      • meeting people who think our role is a waste of time,
      • Technical Writing: What’s your view?

Who are we, and what do we do?

Here follows a few prompts about our role:

 

      • 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 NOT 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 are expecting to see results within a short period based on an issue that has continued unchecked for many years, you will be disappointed.

 

There is much misunderstanding regarding the multiple roles technical writers cover withing a business. Many assume we do a cut and paste job and have no idea that writing and managing reams of content is not straightforward. If it were, then companies would not need people like me who can make sense of the problem, offer a solution and complete the job.

 

I make clear in direct terms that our role is vital, and without us, standards of written communications and documentation will forever diminish. Like many technical writers, I am not a one-trick pony as I have other skills which overlap into different roles. We may have one title (technical writer) but have many more titles under our belts.

What skills do you ask? I have worked with many experts and written process documents covering Incident, Change and Problem Management. I have written policy and operational process documents regarding the maintenance of a network. While I may not have the technical knowledge, I could step into a role and manage the network working with technical teams. I also have the following skills:

      1. Business Process analysis
      2. Documentation management (using SharePoint and Confluence and other DMS),
      3. content writing,
      4. process writing.

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
      • don’t 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 our responsibilities.

What do we offer?

We provide a link between the business and the users by helping users to understand the potential of the product.

Knowledge management

if the knowledge resides in the head of a team member 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 anyway!

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 which 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 quality of the documentation. 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,
      • unrealistic deadlines,
      • 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 – development is more important

If that is the case, then 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 its 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 well

That 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:
          • more efficient,  
          • 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.