Photo by Thom Milkovic on Unsplash

Technical Writers: Beware These Red Flags

Be prepared to walk away.


A technical writer is rarely hired into a new project; hire is usually into a project that has been in progress for some time. The hiring company needs to impart the information the writer needs to work and should have made preparations to do so. This information comes from people who are already busy in other capacities and who are probably not adept in organizing the information, since this is after all what you have been hired to do.

You will know within two days, perhaps within hours, whether or not your work is going to be successful or not and you need to be attentive for these warnings that trouble lies ahead because that trouble will come swiftly.

You will likely have a variety of tasks to fulfill, including at least one of

  • User Documents
  • Internal Documents
  • Regulatory Submissions

Often you will be required to create diagrams and visual aids and should be well-versed in tools like LucidChart, Gliffy, or Visio.

Your writer is a software developer of three decades experience who has done a substantial amount of writing within developer roles almost since the beginning and recently held the job title of Technical Writer several times. There is a long hostility at software companies toward documents and the methodologies currently in vogue explicitly deprecate documentation.

I’ve had jobs that went spectacularly well and others that I could see within hours were not going to work; you can spot the latter immediately and should be prepared to walk away before your client decides that your lack of productivity is your fault.

Hereafter I will simply use the term “writer” instead of “technical writer,” since the topic is not writing fiction nor blogging.

Red Flag: Knowledge Transfer

Image from

Before you can fulfill your writing assignments you need to know about your topics. That means that your new employer has to actively engage in a knowledge transfer so you not only have enough information to write, but enough to write authoritatively.

It’s your first day. Congratulations, you’ve been hired; your portfolio of previous work was persuasive. You meet your new manager, you meet others whose work will be part of yours, you learn who to go to with questions, as you will have lots of them.

From here things can go three different directions.

This is the best introduction. You spend hours on presentations, walkthroughs, discussions; taking pages of notes. It’s OK if this information comes in disorganized form; it’s your expertise to sort it into logical order. But people are ready; you are clearly expected. You have a user account so you can do your own investigations. If your first day starts this way you are off to a good start.

Photo by Christa Dodoo on Unsplash

Your manager is unprepared for you and has not done much to explain to you what you need to work. Instead he points you to a pile of links and internal documents. OK, this may work, you are after all a very literate person and accustomed to learning on your own.

  • If you’re lucky these existing documents are clearly explanatory; if they refer to internal company lore, it is defined before reference. You may need to take notes and flip back and forth but you can figure it out.
  • If you’re not so lucky the information you are presented will be written with the assumption that anyone reading it is already steeped in company nomenclature; uninformative project names, mysteriously-named components, unexplained references. This is bad.

This may be salvageable; perhaps a few questions will clarify but if you are pointed to a bucket of indecipherable material and nobody has taken time to prepare you to read it, you’re off to a bad start. Rescuing the job at this point depends on the willingness of managers and others to explain, but they should have already done so. Judge by their reactions when you ask for detail.

Introductions finished, you are simply given a list of deliverables and nothing else. This was my experience at a recent gig that lasted only a few days. I had no help in getting the information I needed to write anything; I should not have had to ask. It seems quite mysterious, as though my arrival was unexpected.

It might be possible to salvage the job at this point but the company is clearly unprepared for the knowledge transfer that anyone with half a brain knows you will need. If you are contracting through an agency you should contact them immediately; if you are freelancing on your own you are probably in a bad place and given this unpreparedness you have no reason to expect anything will get any better. Walk away.

Red Flag: Unreasonable Expectations

Image from Asana

You have a list of deliverables. They may be verbal explanations or they may be entries in a project management software such as Asana.

The expectations are ridiculously unreasonable. You are told that they expect the first document within a day, and three of them by the end of the week. Unless you are starting with crudely-written documents that only need cleaning up, you have been handed a guaranteed failure; it takes time to learn your way around the information, to generate text and diagrams. The estimated times are based on foreknowledge that you do not have and cannot reasonably be expected to acquire in less than several days.

At this point you need to discuss these expectations with the client and if you can agree on more reasonable times and make understood that you need to learn your way around, the job may be recoverable; if however you are told that their delivery dates are set in stone and you are expected to do three days of work in one day then you are in a man-killer and it’s not worth it. Eighty hour weeks are passé. Walk away.

Red Flag: Regulatory Submissions “ASAP”

You have to do a document that will be submitted to a regulatory agency for review and certification. This is a fairly common job for a technical writer. I prepared one of these for a medical device that was submitted to the Food and Drug Administration; it was 250 pages and the work of four months. As it happened I had designed the software and volunteered to write the submission so I needed no help other than examples of the requisite format.

But if you are given a task like this and told to dash it out in a completely unreasonable time (we need this “ASAP”) then you are in a world of hurt; such documents need to be scrupulously precise and detailed and even an inadvertent inaccuracy can open the client, and you, to legal reprisal. Do you need headaches like this? No, you don’t.

If the client expects something as critical as this in a big hurry then you don’t want to get involved at all. You should give the client one chance to slow down and allow you time to do it right. If they have deferred the work so long that they now need it too quickly for you to do it properly then you absolutely should walk away. This is trouble you absolutely don’t need.


Technical writing is a good career and can be very rewarding. But you must beware clients who expect mind-readers and miracle-workers. I have had jobs that went many different ways; from structured explanations and accounts ready to use to the very worst described above.

Know that a company that expects you to know everything about its products and purpose the day you start is very unlikely to work out; if you do manage to fulfill their tasks it will be at the expense of considerable stress.

American Software Developer living in Vietnam. Classical musician (guitar, woodwinds), weightlifter, multilingual, misanthrope • XY

Get the Medium app

A button that says 'Download on the App Store', and if clicked it will lead you to the iOS App store
A button that says 'Get it on, Google Play', and if clicked it will lead you to the Google Play store