Developer Experience is a relatively new concept to UK software engineering departments, and it can often be typecast as tooling, most often CI/CD tooling of some variety. That is just scratching the surface of what makes a a good DevEx, or more importantly, what makes a bad one. More often than not bad processes, culture, or organisational structure can cause more issues for an engineering department than the tooling could. In this post I’m going to outline some common pitfalls that can cause a bad developer experience, what impact they can cause, and how they could be resolved.

Poor Documentation; or How I Learned to Stop Searching and Just Ask The Expert.

Documentation is a common failing at organisations. This is often due to tight deadlines and the absence of historical documentation. As a result, even if a developer wants to write supplemental documentation to support a change, they may need to create large amounts of supporting documentation. This is not to mention outdated documentation that, through lack of updates, becomes misleading and potentially more of a risk than having no documentation at all. Additionally, documentation is often split between multiple sources, whether in Git repositories with the source code, in tickets, on a wiki, or most likely, a mix of all three and more.

This can cause a whole plethora of problems. Poor documentation poses a risk during incidents, where a solution that could have been written down must instead be figured out from scratch. Critical systems may also end up with no one knowing how they work if all the experts move on. On top of that, a developer can often spend 25% or more of their time just looking for information.

A major risk of bad documentation is the emergence of hero culture—where a single person becomes the go-to source of knowledge, effectively turning into a bottleneck. This issue is even more concerning when considering the bus factor. The factors that lead to poor documentation, and by extension hero culture, are rarely conscious decisions. Instead, they result from years of accumulated issues: lack of time to write documentation, multiple knowledge bases existing in parallel, and documentation being continuously postponed. By the time the problem is recognised as a serious risk, setting aside time to catch up on documentation becomes a challenge in itself. It can seem like such a monumental and daunting task that it keeps getting delayed, only making the issue worse.

So if clearing the backlog of documentation at once is an unlikely scenario, what can be done? Well to appropriate a popular saying:

The best time to start documenting was 20 years ago. The second best is now.

More than just writing documentation, I’d suggest keeping it in Git alongside the source code. Platforms like Confluence, SharePoint, and Jira may be moved, dropped, or replaced, but the source code is highly unlikely to go anywhere. I also highly recommend adopting Architectural Decision Records (ADRs). Despite the name, ADRs aren’t just for architecture decisions—they can document significant decisions made during 3 Amigos sessions, refinements, or any other discussions. The ADR format ensures that key information is captured, including who was involved in the decision, when it was made, what alternatives were considered, and whether it supersedes previous decisions.

This approach helps tell the story of a project—how it evolved, why the code is structured the way it is, and the reasoning behind past decisions. This can be invaluable when onboarding new team members and maintaining long-term project clarity. Remember too to not try to boil the ocean, as it could be just as much a risk burning out as it is with anything else in a developer role, and just like with code, documentation should be tested, as biases and assumptions of knowledge can easily sneak into documentation.

Standards? Where We’re Going, We Don’t Need Standards.

As organisations scale quickly, one thing that can easily get out of hand is standards. Especially as teams tackle the same problems in parallel, whether it be CI/CD tooling, templates, libraries, or any number of other things. This can make it difficult to work between teams with different ways of working, and in extreme cases, can lead to tribal/us-vs-them mindsets.

This undifferentiated heavy lifting cause issues for both any teams needing to work cross implementation, as they have the increased cognitive load of needing to learn a different way of working, then recall which way of working they are currently supposed to be following based on what code-base they are working with. It also causes headaches for anyone ensuring that these competing pseudo-standards meet requirements e.g for security, quality, liability, as instead of having to check 1 standard, it can be several, then getting a plan to get them up to spec, and ensuring it is followed can be a whole extra headache.

To make matters worse, often by the time this issue is properly identified, it’s too deeply entrenched to be easily eliminated, and it can easily end up becoming part of the culture. So when a standard is attempted to be created around something, there could be push back from the developers on a perceived cutback of their autonomy from a decision being potentially viewed as arbitrary. Even if the developers are on board, it can be hard getting the time for the developers getting their code-bases using the standard, due to potential lack of perceived value for the stakeholders, and even if there is, timelines may not allow for it. This also means that even splashing out on a platform team to help maintain this tooling might not get the benefit it was believed to, or at least not as rapidly as hoped.

So how do you get everyone onto the new standard? Well it’s important to pace yourself, similar to the documentation problem, don’t try to boil the ocean. It could be as simple as a lack of understanding, so ensuring explanations for these standards, why they’re necessary, and how the decision was reached can help alleviate the concern from developers. Plus explaining how removing these duplicate standards can help productivity and agility in the long run can help get stakeholders on board.

Outside of that its just a process of working through the teams, gaining an understanding of the reasons behind the resistance, and trying to work with the team to reach a compromise, these issues could be:

• Loss of autonomy - in this case, trying to find a way to allow the team to have their own solution, while ensuring it meets the requirements of the standard, e.g with Harness’ ability to allow developers to build their own pipeline, as long as it meets requirements set by an admin i.e having required quality checks.
• Lack of confidence in the chosen standard - This will be a case of hearing out the developers concerns, and if they’re legitimate, either see if they can be resolved, or be open to changing the standard. If the concerns aren’t seen to be legitimate, work with the developer to alleviate the concerns.

To prevent a re-occurrence of this issue, its important to have a proactive panel setup, with representatives from a wide range of roles, to help decide these standards before there’s multiple implementations in place. Once these standards are being created, they should be clearly communicated, with an easy way of finding what the standard is for a given use-case, with supporting best practice documentation available. This will allow standards that are likely to be widely agreed on to be created, and will help prevent the issue of standards being created in a vacuum, with nobody adhering to them.

Death By a Thousand Forms

Bureaucracy, especially in common parts of the workflow can kill productivity and agility, while providing little to none of the governance they were intended to. Change Management is often a function that heads down a route of increasing bureaucracy, as its perceived these checks and balances protect the path to production. These sort of systems are often brought into place in response to a high impact incident caused by a change, or a perception of a high change failure rate, and often include filling out some form explaining the change, how risky it is, the impact, and details like roll-out and rollback plans. If the change is perceived as high risk, or unusual, it may be brought to a Change Advisory Board (CAB), made up of business and tech representatives, who are well suited to interrogate the safety of a planned change, and if all requirements have been considered and met.

In theory this appears to be a sound way of reducing risk on the road to production, but it fails to take into account the way people react to bureaucracy, and high barriers to entry; they put it off. This in essence forms a workflow of developers put off performing releases, and bundle changes, to avoid going through the change process any more than is absolutely necessary. This delays the realisation of the value of these changes for stakeholders, and makes the releases more risky, as more work gets bundled together, and it becomes easier for a defect to sneak through. This bundling also means that the trunk of the repositories isn’t always in a releasable state, so if a production incident were to occur, rollbacks or hot-fixes become the only options. These issues feed back into the problem of releases being perceived as risky, and it becomes a negative reinforcement cycle.

Left unchecked, this negative reinforcement cycle can consume an organisation. An us-vs-them culture can form between engineering teams and the change management team, where developers avoid innovating or making changes unless absolutely necessary, just to avoid the burdensome process. Over time, the organisation shifts from being proactive to reactive, losing its agility. Developers become unmotivated, and a lack of trust in their ability to make changes only worsens the problem.

This erosion of trust and innovation leads to a brain drain, as talented developers leave for more dynamic organisations. As expertise is lost, major incidents become more frequent, further feeding into the negative cycle. The natural outcome of this scenario is a stagnant organisation, drowning in technical debt. Engineers lack motivation and deep technical knowledge, struggling to innovate under the weight of bureaucracy and constant firefighting, which becomes business as usual.

The solution to this downward spiral is twofold:

1. Shift from Roadblocks to Guardrails

   Instead of micromanagement, organisations should implement safeguards that prevent unintended consequences while maintaining flexibility. For example:

   • Using an automated request system for temporary write access to a cloud console, preventing click-ops as the default while still allowing access when needed.
   • Embracing policy as code and automated checks within CI/CD pipelines. Instead of relying on manual checks, integrate tests for automation, performance, security, and compliance directly into the deployment process.

2. Cultural Shift through Education & Process Change

   Organisations must recognise how excessive manual processes increase risk, leading to bigger, riskier changes and unresolved technical debt. By leveraging data, they can transition from a “change request” model to a “change notification” model. In this approach:

   • Change forms are automatically filled out and act as a log rather than an approval gate, aiding post-incident analysis without obstructing progress.
   • Smaller, atomic changes with feature flags are encouraged.
   • Fixing forward becomes the default instead of rolling back.

   These shifts empower developers to experiment and iterate without the fear that every failure will result in heavier restrictions the next time they deploy.

Step by Step

Developer experience isn’t just a nice-to-have, it’s the foundation on which engineering productivity, innovation, and job satisfaction are built. No matter how many new tools, frameworks, or initiatives a company introduces, if core issues like poor documentation, a lack of standardisation, and bureaucratic roadblocks persist, all other improvements risk being undermined.

These anti-patterns don’t just slow teams down; they create frustration, increase cognitive overhead, and drive talented engineers away. When developers struggle to find information, wrestle with inconsistent systems, or spend more time navigating process than writing code, the result is a sluggish, demoralised engineering culture.

Fixing these problems isn’t optional, it’s essential. Organisations that fail to address them will find themselves in a constant cycle of inefficiency, with every attempted improvement hampered by the same recurring obstacles. On the other hand, companies that take DevEx seriously, by prioritising clarity, consistency, and efficiency, will unlock their teams’ full potential, delivering better software, faster, and with greater satisfaction.

#DevEx