Mind the trap! Antipatterns, a common type of problem in technical writing

This collection is compiled from personal and shared experiences as well as from antipatterns from the field of IT that appear directly or similarly in technical communication and its surroundings. They are in no particular order.

This collection does not fulfill any scientific requirements and is rather intended as a guide for practitioners. You may find that you use some of these patterns yourself; others you will encounter because someone else is applying them.

You probably came here from my talk 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!

(Also if you think this is REALLY helpful to you, send me a crate of your favorite beer :) )

Organisational Antipatterns

Scavenger: The documentation is only created at the very end of the 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 addressed in the documentation.

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.
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 Apple and Microsoft products are a good example).
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.
Bikeshedding: Spending too much time on trivial decisions (e.g. decorative design elements). This is fuelled by the fact that more people can contribute to simple questions than to specialist problems. – (Allegedly, the name stems 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.)
Escalation of Commitment: Sticking to a decision once it has been made and defending it, even if it turns out to be less than ideal. Any doubt about the decision is interpreted as personal attack.
Mushroom Management: Keeping employees guessing and misinformed about decisions ("Keep them in the dark and feed them shit… and if one head rises above the others, cut it off"). Used because some managers feel that it secures their position.
Stovepipe (or Silos): An organisation in which information can flow from top to bottom, but not horizontally between departments or teams.
Death March: A project is likely to fail, but in order to delay the point at which this becomes apparent, employees are forced to work day and night.
Groupthink: During meetings with collaborative planning, participants avoid bringing in critical points of view so as not to disturb the harmony.
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). – This antipattern might appear in Technical Communication, because Technical Communicators are often the first people outside the development team to inspect a product, but usually have no power to pause a development process.
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.
Frozen Caveman: The manager, the team or both 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. As a long-term result, the department becomes inefficient.
The Last 10% Trap: The final steps in finalising and publishing an information product are underestimated (like fine-tuning, formatting, conversion, etc.).
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...)
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.
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 when they could be productive doing other tasks.
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. Causes are unclear project goals and task assignments as well as low priorities of the topics discussed.
Hero Culture: Anyone who stays in the office longer than their colleagues in the evening is considered a hero.
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's something which actually happens!)
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.

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.
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").
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 is copied and pasted instead of integrated from a central repository.
'Cause I Say So!: Instructions and warnings without a context or explanation as to why a certain activity should (not) be carried out. Users do not understand the purpose behind a task.
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".
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/We 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.
Or: 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