Month: June 2020

Give us a break. We need it. I write with authority and experience with over 25 years of experience as a technical author. My enthusiasm for delivering clearly defined documentation/content strategy has never diminished. Yet, two common issues remain for which I have no answer:

• • • 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 author, but I have many more job titles under my belt. What skills do you ask? I communicate with many experts and produce relevant 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 by 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,
      • 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 do not know 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 experts in IT subject matter. 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 link 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.
      • 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 updated and compatible with their version, you will hear loud and clear complaints. 

Businesses forget their T&Cs contain a clause that explicitly clarifies providing documentation. 

Relax at work! 

We get little 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,
    • unrealistic deadlines,
    • Multitasking—working on other vital projects.

This profession has a high level of stress due to a lack of communication. 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 before deadlines to make the required modifications.

People assume technical writers only write and think it’s a straightforward job. The importance of technical writing will come when they understand:

• • • The actual work we do, as technical writers,
    • 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:

• • • SMEs have their responsibilities, and documents are way down their list
    • gaps in the content are common because they don’t believe certain functions are worth mentioning.
  • A technical writer will revisit the documentation, test for cracks, and add 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.