Summary: I'm a developer, and currently also do support for the stuff I develop. Due to organisational reasons I'm being asked to hand off the 'support' function to a dedicated support team, but they want everything to be 100% in "checklists" that can be followed without detailed knowledge, and I think they're asking for the impossible. Some amount can be made into checklists and documentation, but some requires specialist knowledge and an intuition for problem solving.

I'm a 'senior developer' but also carry out some applications support processes for the systems I work with, which are both internally developed and things like 3rd party system we integrate with ("making our software work with Google Maps to show the 5 closest branches" type of thing). Applications support usually involves troubleshooting, answering questions from internal people, etc. but I don't talk directly to our "end user" customers. The systems we develop/maintain are part of the business but the software isn't our 'product' as such.

Lately due to various factors (staff cuts - layoffs and people leaving and not replaced, inefficient use of developers' time, probably other management reasons) we have an initiative to shift the support-type work to another team (within the company) which already deals with support work for some of our other systems - we're a fairly large, multi-site company so it does make sense to 'centralise' this kind of support work.

As part of this handover we're being asked to create documentation for how to run the various processes (e.g. there are some things we have to do after each Month End), resolving issues etc. So far so good and I have created a number of checklists, how-to guides etc etc. to facilitate this.

Where I'm having problems - and where I need your help :) - is I'm struggling to explain that some processes, systems and problems don't fit neatly into a "checklist", "if then else" thought process as they require a kind of intuition for problem solving, diagnostics, "following your nose" to find where a problem may have originated, etc. We're being asked for checklists, procedures etc which cover all the cases of (e.g.) "what can go wrong and what to do about it".

As an example (please don't get too hung up on the example as I have just made up this one to illustrate the sort of thing I mean):

  • Checklist item - Copy this 4GB file to the 'XYZ' network location.
  • What could go wrong?
  • File doesn't exist so I can't copy it.
  • ok, let's check if the process that was meant to create the file has run successfully, by checking its log file. (Checklist item or common sense)
  • the log file says it failed but doesn't say why! That's not very informative....
  • (expected checklist process for the people picking this up): Follow "file doesn't exist" checklist. Here's a document of things to check for why it failed with yes/no criteria resulting in the step to carry out to resolve the issue.
  • (actual thought process I would carry out): Check the obvious things, nope everything looks fine. Why hasn't it run then?? It's succeeded every time for the last 18 months! Hmm, I wonder what was running at the same time? Could it be a problem with not enough resources on the server, although I've never seen that happen before with this file? 4GB... is that the amount of memory on the machine where it's running? Could it have run out of memory? blah blah blah
    • Following my nose until I eventually find out that it was due to not enough disk space somewhere in the process which after a load of other diagnostics, I find it was caused by a failure of some other process which no one noticed because..... etc etc.

It isn't possible (I don't think!) to create a checklist to completely replace that level of diagnostic, troubleshooting ability that comes from detailed knowledge of the system, experience, and just aptitude for that kind of thing. Maybe 60-90% (depending on the details) can be made into a checklist, and I'm happy to do that, but there's always that 10-40% remaining that doesn't yield to a "if then else" mindset.

Of course part of this issue is over-enthusiastic cost saving and trying to push off senior/expert level tasks onto junior people who can follow a "script" to resolve even the most complex issues.

I need to know how, or whether, I can communicate to the involved people (my managers, their managers, the support people themselves who I am meant to be handing over to) that not 100% can be made into "checklists"?

Currently they are refusing to accept the handover unless/until it can all be documented - we're under pressure to get it handed over but I can also see their point of view in some ways (although I wish they wouldn't apply such rigid thinking).

Help! (actual questions in bold italic in the text above :) as I know 'help' isn't a good Q&A!)

From an emotional point of view I feel a little insulted that they think all the years of knowledge and experience can be distilled into 'if then else' that can be followed without fail... and also because if I could sit down and write out "everything that can go wrong and what to do about it" it would mean we hadn't done a very good job writing the software in the first place! I don't think this is what they intend in asking that, but I do let emotions get ahead of me sometimes. Which is partly why I'm struggling to explain 'rationally' why they're asking for the impossible.

  • How much of this is the actual assignment vs. your interpretation of the assignment? I would think most people understand that a checklist cannot be exhaustive.
    – mcknz
    Jul 9, 2019 at 19:23
  • @mcknz It's pretty explicit, as I've already pushed back a couple of times that "well, you know not everything really fits into this format because there's always other things that could go wrong" etc to which the response was something like (paraphrased) "The checklist needs to contain the things that could go wrong and what action to take -- if you're saying there are things that could go wrong and you can't say what to do about them.... we can't accept this being handed over". Maybe they were resisting picking it up, but I don't know what motivation. (They're there all week!)
    – DippyDev
    Jul 9, 2019 at 19:36
  • 10
    How does the support team handle the other systems they already support? It's relatively common for the first-line support to escalate anything that doesn't "fit" on the checklist back to the development team. If that's what your support organization is accustomed to, you'd simply add an else to the end of every checklist to escalate back to you. Jul 9, 2019 at 20:29
  • 6
    As @JustinCave says, this is a tier 1/tier 2/tier N kind of problem. No checklist can capture everything, no amount of training can prepare people for everything. Indicate where they need to bail out of the rote checklist.
    – John Feltz
    Jul 9, 2019 at 20:37
  • 1
    @Smock exactly what I was thinking, just have each branch's logical conclusion be "Escalate"... with a little box next to it they can check off.
    – Andy
    Jul 10, 2019 at 20:45

8 Answers 8


You're asking "How to communicate that...", but the problem here is not one of communication. The other side understands what you want to say anyway, they just don't want it. Saying it again or in a different manner won't change anything. There are two errors in this process:

  • Work that can only be handled by more skilled people is pushed to less-skilled ones with the intention of cost-cutting.
  • It's not clear who actually decides when the support side of it is "handed over". Is it they who decide on it? If so, they can keep rejecting it forever. Is it you? In that case, you can just say "I have handed it over to you, whether you accept it or not is not my problem". Or is it someone else - some manager above both of you? In that case, discuss it with him.

Again, the problem is not one of communication. Someone (the management) is demanding the impossible (that you simplify what cannot be simplified to the degree that low-skilled people can do it), the other side (the support group) is defending themselves (as can be expected) (and face it, if they were skilled enough to do the level of investigation you described, they would have been developers, not support), and you're in the middle.

Your goal here is to extricate yourself from the situation, which means, to convince whoever is your boss that you did what could reasonably be done, and need to be moved from that to other projects.

If neither side is willing to admit reality, well, in the worst case, it might be good to start looking for the next job (while you have this one).


how to communicate that not everything can be part of a “checklist”?

Some ideas listed below, but ultimately, you may need to push back, and be more assertive. They may not really know what they are asking for, but figure as long as they keep asking, you'll just keep on giving. You may have to stop playing the game.

You may also need to do a reality check against yourself -- certainly you can keep thinking of contingencies and potential points of failure and divergence, but there is a limit to what is reasonable and rational.

At some point, you'll need to shift the burden back on them, so when they ask -- What else is there? -- you'll have to say: That's all I can think of. That's when they will have start solving problems for themselves.

  1. Appeal to definition

    Explain to the support team that there are limits to any checklist, and they are by definition summary in nature. If you needed to describe every possible interaction, you would be writing a manual in book form. A list is not a manual.

  2. Appeal to authority

    Describe your issue to your managers, tech leads, subject matter experts, or other supervisors. Ask them to help you communicate to the support team. There is strength in numbers.

  3. Appeal to example

    My favorite is the peanut butter and jelly checklist, which you can find just about anywhere online. If someone creates a checklist on how to make a PB&J sandwich, and another person follows it literally, the result is usually disastrous. The example shows the limitations of written instruction.

  4. Appeal to absurdity

    Actually create a simple checklist that is ridiculously detailed. Perhaps once they see one for themselves they will understand that they are less than useful.

  5. Appeal to deadline

    Tell them you would be happy to write extremely detailed checklists. Ask them how long they can wait.

  6. Appeal to exhaustion

    Keep sending them slightly more detailed drafts until they are tired of asking for updates to them.

  7. Appeal to pride

    Ask them if these checklists should be at grade-school level or higher.

  • 1
    I actually LOL'ed to No. 7.... If I where to assign priority over the points you made: 2 > 1 > 3 > 5 > 6 > 4 > 7
    – DarkCygnus
    Jul 9, 2019 at 22:35

"they are refusing to accept the handover unless/until it can all be documented"

Is it feasible to document "everything"?

I put everything in quotation marks you are trying to deal with a silly request. One option is to give a sensible response (i.e. just do good documentation) and apply a silly label it to fit the silly wording of the original request.

You are currently looking at it from a troubleshooting perspective but the problem would be more solvable and more coherent if you look at it from a documentation perspective. Instead of documenting every possible error just ensure that:

  1. Common errors are documented - put these in a "checklist" section if you like
  2. All of the remaining processes are sufficiently well described that someone with a bit of common sense can piece things together

Bundle this together and say "everything is documented".

  • The thing is, how can one know a priori all of the remainder possible issues? ... yes one can not, and that is the issue here as some people are expecting the list to cover all possible issues when such thing is highly unlikely to be doable.
    – DarkCygnus
    Jul 9, 2019 at 22:40
  • The point of my answer is to document processes rather than issues. The OP has been given a bullshit/impossible task and this is one way of completing it. Jul 10, 2019 at 16:59
  • I see now, wasn't that clear to me that you were talking about processes (perhaps what confused me was that point 1 says errors and then point 2 says processes). I understand your approach now and think is a good idea :)
    – DarkCygnus
    Jul 10, 2019 at 17:02

I won't go on at length about how this is misguided because that's not your fault, but just for the record this is why development teams shouldn't shift off app support to "lower skilled" teams, because if it's a "routine" problem they should fix it in the software to eliminate the toil and if it's an "advanced" problem you need an engineer to figure it out. Best case but still not as good as eating your own dog food is a highly skilled SRE team that can figure complex issues out. But, on to the question at hand.

Probably the best you can do is offer an escalation path. "Follow this checklist, if it doesn't solve the problem, escalate to development." This gives them an out so they don't feel like they're stuck with something it's impossible for them to solve, it also encourages you to make the checklists good enough that they're not wasting your time with the truly routine. Sit down and work with support people (not their manager, someone who works for a living) to figure out what they know/don't know and how you can best set them up for success.


For stuff like this I've normally seen some type of escalation path.

Tier 3 would be a help desk or junior DevOps functions. They would They would handle most issue resolution or recurring tasks. Checklists would be something like "If this happens then blah, blah. If this does not resolve the problem then escalate to Tier 2".

Tier 2 would handle more complex issues worked by more experienced DevOps people. If they were unable to resolve then it would be escalated to Tier 1.

Tier 1 is (usually in my experience) the development team. Anything that reached this level is severe and needs developer input.

Anything that would make it to Tier 1 would (after it's resolved) need to have a "lessons learned" session with members of all three tiers. This would not be an optional exercise. Possible outcomes could be more training , updating on FAQ's/knowledge bases, future enhancements for the DEV team, etc.


Make checklists of the most common faults/fixes. Things that require more product knowledge: "..contact the software manufacturer/forum for more info".

  • Hello and welcome to The Workplace. I see your answer has a good point: to indicate that unexpected errors should be escalated to you or the dev team... however, I feel that your answer would be better if you enhanced it (explain why your suggestion is useful, perhaps provide an example on how to phrase such thing, etc.)
    – DarkCygnus
    Jul 9, 2019 at 22:38

I've seen obsession with checklists where I work as well. I suspect it starts when some manager reads an article in HBR or some in-flight magazine and sees how it works great for airline pilots, astronauts, and surgeons and is then eager to implement it at work with the expectation that checklists can make their own operations as predictable and tame as taking a flight to New Jersey.

The problem is that, as you noticed, not all work functions are amenable to a checklist approach.

But that's OK!

A checklist is perfectly fine starting point and the people doing the actual work will soon enough get wise to the fact that it can't cover every possibility and that some "items" on the checklist will require research, workarounds, and sometimes help.

Look at it this way, you probably did not enjoy the benefit of a checklist when you started. These new folks might not be "as ready" as your team was, but it's a chance for them to advance.

Many people make quantum leaps forward in their career when they're thrown into something that they're not fully ready to do. You should see this as giving the new team "a break".

  • And the checklist doesn't work for astronauts when something unforeseen happens.
    – gnasher729
    Mar 6, 2020 at 21:57

As others have pointed out, the key to resolving this is to cover what you can of immediate fixes in the checklist and make checklists "stop" at a certain point with "escalate the problem to the developers of the software." That checklist item should include details of how to escalate (or lead to an escalation checklist with those details); these details should include in particular documenting the original situation that led them to go through a "handling errors" checklist and which checklist items they then executed.

The initial problem is to get the support team management to accept a checklist with escalation items on it. You've not indicated whether or not you've tried this yet. If you haven't, it may be as simple as just putting escalation on the list and leaving it at that.

If that's not acceptable to the support team management, making it more clear where the responsibility lies (or more precisely, where you want the responsibility to lie) may help: document reaching such a point explicitly as exposing a software bug or problem. (If the logfile isn't informative enough for those using it, this is indeed a problem with the software. But don't take this to mean you need to commit to fixing that in the software itself; for more on this see below.) Depending on your organization, you may need to make the phrasing more politically palatable by calling it a "potential software issue" or some such thing.

You may get a response, either from your manager or from the support team manager, that bugs are not acceptable. Whoever makes that complaint, at that point you need to bring in your manager to help decide what to do about this. Many of these situations are ones where you can see the general type of thing that can go wrong but it's not worth doing a lot of detailed analysis and development work to try to handle the general case; it would be a lot faster and cheaper to resolve specific problems if and when they come up. (The resolution may or may not involve changes to the software; you'd balance the cost of implementing any particular change by how much time it's likely to save you in the future.)

I suggest resolving that by opening a new feature/bugfix request (an official one in your tracking system) that describes that general case, making it clear that there's a lot of expensive analysis to be done before the improvements could be developed, and offering the alternative of "rather than doing now this expensive thing that we might not even ever use, add an escalation to the checklist."

At that point you've got your CYA, and hopefully management now has an understandable explanation of how they can save time and money by putting escalation on the checklist. At any rate, the choice is now clear and it becomes a negotiation amongst the stakeholders about whether software developers' time should be spent now trying to cover this case before it happens (instead of on other features) or whether the software development organization should commit to a fast response later if the case ever arises.

Alternate Approach

An alternate approach, if getting escalation in the checklist seems to be very difficult, would be to "hide" it in the checklist by simply not addressing the issues that would require escalation.

Working with your example, this would mean saying, "check the log file and resolve the problem indicated there."

I would avoid this approach if I could, both because hiding things isn't good and because you may get pushback to list all the problems that could be shown in the logfile, which ends up pushing you back to the solution above anyway. But this technique may at least help resolve the short-term problem if fixing things "properly" is too difficult.

You must log in to answer this question.

Not the answer you're looking for? Browse other questions tagged .