Mind the trap! Antipattern list

You probably came here from one of my talks, maybe at the tcworld conference in Nov 2023. Happy to see you here! If you have further questions or want to contribute, feel free to contact me!

This collection of antipatterns is compiled from personal experiences as well as from input from colleagues and antipatterns from the field of IT that appear directly or similarly in technical communication. The order is random.

This collection does not attempt to fulfill any scientific requirements. It rather is intended as a guide for practitioners.

Organisational Antipatterns

Scavenger: The documentation work starts only at the very end of the product development process. The documentation team has no way of influencing product development beforehand. Even worse, sometimes problems are not solved during product development, but are instead pushed off to the documentation.
Instead, start writing in parallel to the product development process. Use early product sketches as first input and add iteratively.

Analysis Paralysis: Right from the planning stage, attempts are made to pre-plan every detail to absolute perfection. The situation is completely over-analysed without any real progress being made.
To avoid that, create a structure in which you can work but which is flexible enough to react to adjustments where necessary. Also: Plan in phases. Perfection for the next step (e. g. next day/week of work), rough planning for further steps, drafts for anything beyond that.
Vendor Lock-In: When selecting tools or aids, you commit to a manufacturer to which you are subsequently bound and to which you remain at their mercy. Often in connection with proprietary data formats, connections or spare parts. Many products e. g. from Apple and Microsoft are part of an ecosystem that can only be expanded by paying those companies more money.
In order not to be handcuffed to one company, use tools that work with open standards, file formats and interfaces. Before buying a tool, check if there are alternative manufacturers you could switch to if necessary, and calculate how costly (in time and money) a switch would be.
Premature Optimization: Work on a task begins before a worker is familiar with the complete document or product and has an overview of the task or the consequences of their actions.
Since knowing the entire product in all details right from the start is a pipe dream anyway, start with the things you do know or which are apparent (like the user interface) and write drafts at first. Make your way from there and review your drafts once you feel safe with the product.
Bikeshedding: Spending too much time on trivial decisions (e.g. decorative design elements). This is partially due to the fact that more people can contribute to simple questions than to specialist problems.
Allegedly, the name originates from a situation in a city council where the decision to build a power plant was made within a few minutes, but afterwards people discussed at length about the color of the bike shed.
If you might run into a Bikeshedding situation, plan the discussion beforehand. Make sure that the "big" decisions are done and dusted before the peanuts come up. If possible, outsource the trivial decisions to a smaller committee.
Escalation of Commitment: Sticking to a decision once it has been made and defending it, even if it turns out not to be ideal. Any doubt about the decision is interpreted as personal attack.
Should you encounter an Escalation of Commitment from your manager or colleagues, consider the background of the decision. If you have to sway this kind of decision someone else made, take the context into account and show why it might have been correct then, and why it might not hold up under current circumstances.
Mushroom Management: Keeping employees guessing and misinformed about decisions ("Keep them in the dark and feed them manure… and if one head rises above the others, cut it off"). Used because some managers feel that it secures their position, or that they were useless otherwise. In extreme cases, a manager might insist that only they are allowed to participate in meetings with other teams and that all information must flow through them.
If you are one of the employees, you need a looot of tact now. Divert the attention of your manager from the daily work to questions of politics. If e. g. you are trying to set up a new project, ask him to ensure the corporate policy support with the higher-ups, while you do the operational work.
Stovepipe (or Silos): An organisation in which information is isolated inside the departments and can flow from top to bottom, but not horizontally between departments or teams. This might even lead to redundancies, when e. g. multiple teams create documentation in parallel.
Sometimes you cannot change the corporate structures. In that case, connect to the persons responsible in the other teams and create an informal network.
Death March: A project is likely to fail, but in order to delay the point at which this becomes apparent, employees are forced to "fight" until the end.
Once you notice you are part of a Death March, shift your focus from finishing the project to salvaging anything useful that might come from it. Maybe there were useful insights or concepts you could use later on. Project details or even the project foundations could become part of the next project. If you are not in a role to make that switch, make sure to not be blamed later on.
Groupthink: During meetings with collaborative planning, participants avoid bringing in critical points of view so as not to disturb the harmony or be seen as troublemakers.
However, what seems to be critical to you might not be critical to others, or there might even be a solution already you don't know of. Instead of pointing out issues (which might come across as dismissive), ask what others think about it.
Bystander Apathy: An observer notices bugs or problems with a product, but decides not to do anything in order not to cause bigger consequences (e.g. because the deadline for changes has passed). In Technical Writing, this might occur since Technical Writers are frequently the first person outside the development team to inspect a finished product, but usually don't have the power to influence the development process.
Try not to be the apathetic bystander–notify the person responsible anyway. They might have not realised the problem yet, after all. Document that you reported the problem and leave the solution up to them.
Copy Folder Versioning: This anti-pattern occurs if insufficient tools are used. For new versions or variants of a document, the corresponding file or directory is copied and the copy is modified. The result is an unstructured mess of files and folders in which it is impossible to go back to an earlier version or track changes.
Use a versioning system instead, e. g. Git or SVN. Most documentation tools also do have some kind of versioning included.
Frozen Caveman: The organisation, the manager, or the team are unwilling to learn new ideas and techniques. They are comfortable with the status quo, are afraid of change or have a reasonably well-running cash cow and therefore no pressure to change (Innovator's Dilemma). As a long-term result, the department becomes inefficient. This might even lead to companies folding if they cannot adapt to market changes (like Nokia or Kodak).
If your organisation consists of Frozen Cavemen, try to set up an innovation process. Set some time aside (even if it's only a few minutes every week) to try out new things. Be open about the results: Don't expect new ideas to be useful or to work right away, and don't be afraid to drop/shelve ideas, if they are not useful.
The Last 10% Trap: The final steps in finalising and publishing an information product are underestimated (like fine-tuning, formatting, conversion, etc.).
Set up a robust review and publishing process using automation. Don't postpone fine-tuning until the very end, but rather cut up your work into smaller pieces that can be finished independently. If you spend a lot of time formatting your documents, their structure might be too complicated.
Shiny Toy: The idea that all current problems would be solved with a brand new tool that just entered the market. (AI tools might come to mind...)
Whether the new toy is really helpful or not, it might be worth testing. Start with a test run in a sandbox. Evaluate in parallel what exactly is wrong with your current processes or tools, and then compare if they are really solved using the new tool. Also be careful not to introduce new problems.
Confusion of Objectives: The personal goals of a manager are not congruent with those of his team or the organisation, but are prioritised in his decisions.
If you are below that manager, there is no real solution. Document everything and make sure blame will not be deflected to you. Sorry.
False Economy: When implementing cost-cutting measures, management does not take into account the indirect consequential costs. Perceived and actual costs and cost savings deviate from each other. Examples include complicated, time-consuming procurement processes for infrastructure or tools which delay the point in time at which new tools start paying off. Another example is viewing existing employees as being ‘there anyway’ and burdening them with tasks outside of their area when they could be more productive doing their own work.
Since this is in most cases a management decision, you can only point out the problem if you are below management level. Not to sound defeatist, but usually there is not much you can do…
Groundhog Day Project: Meetings are held regularly on a topic or project where the same issues are discussed over and over again. The meetings end with the conclusion that ‘something should be done’, leaving everyone with a warm feeling but no action. After a while, the discussion is repeated nearly word for word.
Though, if nothing was done and yet there was no problem, the issue might indeed have been expendable anyway, so drop it. Otherwise: Clarify project goals and assign tasks with a measurable outcome. See also: SMART criteria in project management.
Hero Culture: Anyone who stays in the office longer than their colleagues in the evening is considered a hero. – F*ck hero culture, just go home. Meet some friends, have a drink, go play with your kids.
Management by Numbers: Measuring the success of a department/team solely on the basis of numbers that are hardly suitable as a metric for the effort involved (e.g. lines of code, number of pages of documentation) and making decisions solely on the base of this number. (If this sounds stupid to you, that actually happens.)
However, if your manager wants code lines, give them code lines. The line break was invented for a reason. Seriously, you don't need to justify someone else's bullsh*t ideas.
If you are that manager, you might have a huge trust problem. Talk to your people on what they consider to be a measure of progess, and forget the idea that complex project could be broken down to oversimplified indicators.
Diluted Responsibility: For fundamental decisions, a group is assembled which is so large that the decisions can hardly be traced back to individual persons. Decisions are made on the basis of the lowest common denominator and are therefore lacking in courage.
In this situation, check with the people in the group if they are really passionate or if they just don't want to be blamed. Work together with the people really invested in the topic. Also, while the ethics of that might be questionable, sometimes it helps to frame a new concept as "innovative" or "sustainable" or whatever buzzword is common in your company – nobody wants to block that.

Antipatterns in Documentation Architecture

Spaghetti Manual: A sequence of instructions that requires you to jump into sub-sequences somewhere else for parts of your action or to switch back and forth between different instruction manuals.
One for All, All for One: A single manual is published for all variants of a product, and users must find out for themselves which instructions apply to their version and which do not. (This is often the case with car manuals.)
Play Child: Using all the features of your authoring tool or Content Management System to the extreme. The resulting documentation base and the end results are almost unmaintainable because of too many conditional texts, variables and other control elements.
Shotgun Surgery: A document structure where small changes in content require many minor adjustments in many different places ("operating out shotgun pellets").
Fort Knox: Online documentation is locked behind a login barrier, or it takes other kinds of effort to access it. Just remove the login barrier and be sure your documentation is well accessible from the website as well as indexed by the major search engines.
Boat Anchor: Planning a documentation structure ahead for hypothetical future expansions – and then desperately sticking to this structure even if the overall situation has changed.
Design by Committee: Many contributors to planning, but no common vision. (Related to Diluted Responsibility)
Architecture by Implication: Decisions are not made explicitly, but everyone makes them ‘ad hoc’, on the assumption that colleagues will see the problem in the same way. The result are inconsistencies because everyone brings their ‘own flavour’. (There are software or documentation projects where you can recognize the designer of every single part.)
BDUF - Big Design Up Front: Creating a detailed structure before the first line of text is written - inflexible to changes in the product development process or to insights that emerge during the working process.
Speculative Generality: All sorts of eventualities are anticipated and provided for, leading to an inflated and unnecessarily complex system.
Duct Tape Documentation: Always running after the current problem (or whoever shouts the loudest), no long-term planning or advance work. – This sometimes happens with service providers who work somewhere for a short time only.
Uncommunicative Name: Names or descriptions that don't provide any useful information about the content ("New Figure 1 edit_new.docx").
If there is really really no better way of working, set up a distinct directory for each document file and name the files manually after the saving time and/or date (2025-12-25--18-02-parts-list.docx).
Golden Hammer: A tool or a way of working that is familiar and has been successful in the past is used for different tasks without consideration if it fits.

Content Antipatterns

Copy & Paste: Text or any other type of content that is used in multiple places is being copied and pasted instead of included from a central repository.
Set up a repository, put the content there, check if it is really location-independent, and then include it from there.
'Cause I Say So!: Instructions and warnings ask a user to (not) carry out a certain activity, but give no context or explanation as to why. Users do not understand the purpose of a task. In that case, add a short explanation, half a sentence is usually enough.
Example: "Don't tow the car backwards, because that might damage the gearbox."
Echoing: The first sentence after a headline repeates the headline itself. Example: Headline "How to do a thing", first line: "This page explains how to do a thing".
Just skip it. Be sure that the headline is meaningful enough (which you should do anyway).
Overwarning: Warning against every conceivable and inconceivable danger. The idea behind this is to prevent liability risks; the result is that really important warnings get lost in the mass of meaningless nonsense.
Information Diarrhea: Writing every bit of information on a subject one knows or can think of, regardless of its relevance.
Cargo Cult: Copying parts of text from elsewhere into your own works without understanding why and how. – Often seen in security chapters when the author is unsure about the legal situation or when they find something that "sounds good" elsewhere.
Magic Buttons: The explanation of an operating procedure mainly goes along the interface elements, without the reader being able to understand why he is doing what he does ("Press this button… then press that button… then do this… do that…").
Intellectual Violence: The reader is bombarded with technical terms and specialist knowledge above their skill and knowledge level. This intimidates the reader, forces them into a role of inferiority, and discourages them from asking questions.
Gold Plating: Working on a project or task far beyond the point where further effort adds value.
Assumption Driven Documentation: Assumption that the users are on the same level as the author and have the same knowledge and skills. (As they say, bait the hook to suit the fish, not the fisherman.)
Broken Windows: Small problems that are not fixed show a state neglect. Discipline decreases and the problems multiply. This principle is known in sociology as Broken Windows Theory (see https://en.wikipedia.org/wiki/Broken_windows_theory).
Feature Creep: A product is repeatedly extended, making it increasingly complex (often due to stakeholder requests). – Even if this antipattern rarely occurs within the documentation team itself, the documentation has to react.
The Customers are Idiots: Members of design teams believe that internal expertise in the field is an adequate substitute for customer surveys and that conducting customer research is a waste of time and dangerous… because customers are idiots.
We are Idiots: Conversely: Members of design teams believe that internal expertise in the field is insufficient and every design decision has to be backed by customer validation.

jhauser.de