7 UX principles everyone needs to understand to adopt better tools that improve developer experience

‍

In the first part of this series, we discussed that offering great DevEx means optimizing work processes and removing friction so your developers can easily get into (and maintain) flow state. 

In this next post, we’re taking a closer look at tooling and how it impacts DevEx, and help the reader understand what makes a tool that dramatically improves the developer experience. This article can be used as a guide to create better internal tooling, review any commercial or open source tooling used internally to see how it impacts the developer experience, or adopt new tools, commercial or open source that help developers easily get in and maintain flow state.

Let’s dive in.

The DevEx Series

This blog is part of a series of blogs on developer experience, you can view the index so far here

TL;DR

Favor simple tools over complex ones to improve flow state. Tools that offer too many features tend to be overly convoluted, hard to use, set up and maintain. 

DevEx is not the same as UX, but UX is a crucial part of DevEx

• UX is not just UI! It applies to all layers of the tool, be it API, CLI, or UI
• Good UX means intuitive design. 
• Tools with great UX minimize friction and improve the chances for developers to enter and maintain flow state.

Understanding some basic principles of UX can lead to designing, picking, and implementing better tooling:

1. Flexibility and usability are often opposites → More features generally mean more complexity and less usability. Focus on the top features you need. 
2. Leverage constraints to teach and make things easier and safer → Constraining doesn’t mean taking away freedom; it means guiding the user to safer, best practices and narrower focus — more flow state.
3. Design over documentation → Convoluted, large documentation often hides bad, lazy design. Documentation is important, but intuitive design is paramount. Well-designed software makes the documentation less relevant.
4. Provide great feedback → Tools must provide feedback that’s informative (even didactic), specific, contextual, and brief; overwhelming the user with too much feedback is just as bad as not giving enough of it. 
5. Understand how your users see the world → Leverage existing conceptual models, such as existing conventions for colors, shortcuts, etc. It will help make your tool more intuitive.
6. Don’t blame users; blame the design → It’s too easy to call users inept for not understanding your application or not reading the documentation, but generally, these issues are caused by bad design.
7. Use convention over configuration → Provide sane and safe defaults, don’t force developers to provide multiple inputs. 

Measuring success in terms of DevEx can help you choose the right tooling. Look at metrics such as: 

• The steps and time it takes to execute an action
• The total cost of setting up the tool 
• How easy the tool is to set up for a new engineer
• How effective the feedback and error messages are

The metrics you choose will depend on your organization, its goals, and how it operates.

Tooling that hurts the flow state

It may sound counterintuitive, but the worst tool for efficiency tends to be the one that tries to satisfy everyone’s needs — not the one that falls short in doing so. Tools that aim to please everyone and have too many features are often poorly designed and difficult to use, require many steps to set up, and need extensive supporting automations and maintenance.

That’s not to say you shouldn’t use these tools, but it’s far wiser to take the time to develop a deep understanding of the problems you are trying to solve, how they will evolve over the next year, and how they’re best solved now and in the future. Then, with that clarity, you can select tools that satisfy those needs in the most straightforward way possible.

Take Jenkins, for example. It’s by far the most comprehensive CI tool available, and does everything you need (and likely more) via plugins. Its Groovy DSL is also very powerful, giving you almost infinite flexibility to code pipelines. Regardless, Jenkins has fallen out of favor as teams opt for tools like Github Actions or Gitlab CI. Why? Because they are far easier to use and understand.

This isn’t a trend that’s as far-reaching as you might expect. There are many tools that companies still insist on using despite there being simpler alternatives that would still satisfy most (if not all) of their needs. AWS, for example, is extremely powerful and leveraged by companies of different sizes and levels of maturity. That said, if you’re a very small company that’s just starting out, AWS will probably create far more friction than competing platforms that are simpler to use (eg., Heroku, Digital Ocean, Linode, or even Google Cloud).

When it comes to DevEx, choosing extremely complex, overly featured products in your stack can have various negative effects:

• They take far longer to learn, and you may need to reteach the technology often as your staff churns
• They require a far more intensive setup process
• Automation is more time-consuming and requires additional care and maintenance
• Complexity is harder to tackle as the company matures.

Remember: it’s far easier to evolve your stack into something more complex than making it simpler once it becomes overly convoluted.

In what follows, we take a closer look at what makes a tool user-friendly so you can leverage that information to design and pick tools that contribute to flow state positively rather than hurting it. We will also identify some metrics you can use to determine and quantify whether your current tooling offers a good user experience or not. 

What qualities help your tools improve DevEx?

The best-designed tools are the most intuitive. In other words, they require fewer steps to do the job. Ideally, tools should also be aesthetically pleasing so that they draw users in, but this is not a strict requirement. To understand how to achieve these elements, let’s draw from the field of user experience (UX).

UX ≠ UI and DevEx ≠ UX

Let’s start with some definitions. UX doesn’t just refer to the user interface (UI) of a tool, although it is typically discussed in that context. UX means how well-designed and intuitive a tool is, and it applies to the entire journey of using a tool, be it API, CLI, or UI.

DevEx is sometimes equated as UX for developers. We don’t take that stance in this series because, in the context of developer tooling, the same principles of UX also apply to engineers as users — after all, developers are people too (except for Mark Zuckerberg perhaps, the jury is still out on that one). As such, UX has a narrower scope than DevEx.

So, in a nutshell, DexEx is not equal to UX for developers, but UX is an important part of the developer experience.

Understanding the basic principles of UX and how they apply to DevEx

Great UX is great design, it ensures that the user grasps the intended purpose of the tool in the most intuitive way possible. 

Designing intuitive applications is challenging, but understanding the principles of what makes them intuitive is easy. In this section, we discuss a few of these core principles. (If you want to go into even more detail, we recommend this article.)

1. Flexibility is the enemy of usability

In the context of design, too much flexibility is at odds with usability. This doesn’t mean that all your tools need to be rigid and overly simple, but they should cater to what your developers need and how they think. As such, a great tool should have multiple layers, making the most common features visible and abstracting away the ones that are rarely used so they don’t clutter usability or become difficult to learn.

‍

‍

As you choose the features to implement, we suggest leveraging the Pareto Principle (also known as the 80/20 rule). Start with the features that are most useful to your developers, and make sure they’re implemented well. Then you can build from there.

When picking tools off the shelf, this translates to not choosing tools that have a complex and robust suite of features. As we indicated above, your team will be far more agile if you pick simple tools over complex ones. For example, a small startup will probably deliver software faster with something like Heroku or Cloud Run than a full-fledged EKS cluster.

You can always switch to more complex tooling if the need arises, but generally speaking, people tend to overestimate how many features they will need, and then they pay the price with technical debt and time wasted learning and maintaining complex tools.

2. Constraints make tools easier and safer

Constraining is not about limiting developers, it’s about favoring best practices and applying guardrails for errors and mistakes. Constraints can be applied with RBAC, policies, or even the design itself.

Consider a scroll bar that stops at the end; that’s a constraint telling you that the page ends there. Constraints can also give better UX for various personas in a tool; for example, a developer portal could have different RBAC permissions for a project manager, for a developer and a platform engineer. Each of these permissions could effectively hide settings that are not required for their job, making it safer and easier to navigate around the UI.

We previously discussed how flexibility often impairs usability, RBAC based constraints or constraints based on settings can get around this by abstracting functionality based on user personas.

3. Design over documentation

Documentation is often a place where bad design hides. If your documentation is too long, confusing, or hard to follow, then that’s probably a sign that you need a tool with a simpler design. 

In line with this: be wary of picking commercial tools that dump the responsibility of improving the design on the user and disguise it as “we have great documentation you can follow.”

The reality is that it’s easier to dump a complicated process into the documentation than to design an elegant and intuitive tool. However, it is an effort worth spending because it means that whoever ends up using your product will be able to focus on work and get into flow state more easily.

‍

4. The need for great feedback features

Any tools that developers use should be effective at providing feedback as this makes it easier to enter and maintain flow state. If an engineer performs an action and doesn't receive adequate feedback (eg., an overview of what’s happening or an alert that something went wrong), they will need to spend a lot of time doing detective work that takes them away from the task they’re performing. In other words, it breaks the flow state.

Great feedback needs to be informative (even didactic), specific, contextual, and brief. Overwhelming the user with too much feedback is just as bad as not giving enough of it. 

Here is a good example of feedback from the CLI tool Kind:

​​

‍

The example above not only shows what has been done, it also points out where to go next.

Error messages are another example of where feedback needs to be specific, contextual, and informative:

‍

‍

In the above example, we typed a command wrong, and we got the right command back.

Good error messages outline what went wrong, why it went wrong, and provide steps for how to fix it, with either the command to do so or a link to the correct UI page or documentation.

5. Conceptual models  —  how your engineers see the world

The most popular Jenkins plugin is the one that changes blue balls to green to indicate successful builds. This is because most of the world’s conceptual model associates green with success, not blue.

‍

‍

The tradeoffs here are often inconsequential, as is the case with these colors, but occasionally it may be tempting to change to a different model because it feels more efficient. Consider these changes carefully as people may be put off from learning a new conceptual model. That’s the reason why almost no one uses a Dvorak keyboard, even though it’s ostensibly more efficient and comfortable to type on — it takes too long to learn!

Unless you have an extremely compelling reason to go against convention, don’t do it. 

6. Don’t blame users, blame the design

It’s easy to call users inept for not understanding your application or not reading the documentation. However, more often than not, any issues with the usability of an app are caused by bad design. 

Blaming users doesn’t solve these issues. Instead, consider putting on guardrails and designing your application so it is more intuitive. This way, users can’t make dangerous mistakes, and you can leverage user mistakes as learning opportunities to see where your design has gone wrong.

When it comes to selecting third-party tools, we vastly underestimate how costly it is to pick solutions that are too difficult to use — both in terms of engineering hours and accrued technical debt. So, if you are designing a tool for other developers to use, take this into consideration. And, if you are looking for a tool to bring into your organization, always look at how much it accounts for the user experience from a design point of view.

7. Use convention over configuration

When designing tools, especially complex tooling that requires a lot of configuration inputs, favor safe and sane defaults. You can also stretch this to provide templates, most commonly used configuration and best practices. This helps the user understand what good looks like and it gives them a starting point

Self-assess your company's DevEx in the context of tooling

Your company may be unwittingly creating too much friction and hurting flow state by using the wrong tools, but how do you measure this impact to get an accurate, objective picture? Here are some example tooling DevEx questions (or metrics)you can use to measure your existing tooling and set a benchmark for potential alternatives:

• How many steps does it take to perform an action with the tool? → Compare this with other tools to see how much friction you can reduce by adopting another solution.
• How much time does it take to perform an action with the tool? → Some tools may require more steps, but take less time to execute an action. The end-to-end time to perform an action is important, especially if your organization is tracking time-to-market for new features. Again, compare this metric with other tools to see the time saved. 
• How much time does it take to set up the tool from scratch? → See how long it takes an engineer to set up a tool from scratch. It is important to measure this with an engineer that has no previous experience with the tool.
• How much time does it take to automate setup? → The time it takes to automate the tool creation and setup from scratch.
• How many steps are outlined in the documentation to get started with a tool? → Remember that tedious documentation often hides lazy design.
• How much time does it take to maintain the tool? → This includes fixes, upgrades, and maintaining IaC code. Break up metrics based on maintenance tasks.
• How many prerequisites are required to use the tool? →  The more prerequisites, the less likely you will get developers to try and adopt it.
• How much engineering time and effort is invested in the product? → This metric can be used to compare with other tools, commercial or not, to see if it’s worth spending more on a different product. Remember that open source software sometimes has a hidden total cost of ownership.
• Are the error messages helpful? → Do they cover what, why, and how? Bad application feedback will lead to wasted time on debugging.
• Does the application provide meaningful and helpful feedback when using it? → Using the tool should provide meaningful feedback on the actions taken. You can list out the tasks and outline the feedback you want and check whether the tool covers them.
• Does the tool provide adequate safety constraints? → Perhaps you can see how RBAC limits flexibility to personas that don’t require it and how RBAC limits the number of unsafe actions you can perform. You can look beyond this and see how the design itself inherently prevents costly mistakes (For example, with different colors for production vs. dev, safety checks, etc.) 

It’s worth noting here that these metrics are just examples, and you may want to expand or cherry-pick these depending on your company’s situation. Aim for metrics that measure friction. In other words, measure anything that may negatively impact how developers get into and maintain flow state, so you can improve it.

The value of tooling in DevEx

Picking the right tooling is paramount when improving DexEx. The tooling that leads to flow state is the one that lets you do your work in the safest and least amount of steps, and it is the most intuitive to learn. Therefore it is wiser to optimize for ease of use and great user experience rather than the number of features — particularly if the aim is to make it easier for developers to easily get in and maintain flow state.

‍

About the Author

Fernando Villalba is our Developer Relations at OpsLevel, he has over a decade of miscellaneous IT experience. He started in IT support ("Have you tried turning it on and off?"), veered to become a SysAdmin ("Don't you dare turn it off") and later segued into DevOps type of roles ("Destroy and replace!"). He has been a consultant for various multi-billion dollar organizations helping them achieve their highest potential with their DevOps processes. Now he is passionate about platform engineering, developer portals and DevEx, which he feels is where the future of software delivery shines brightest.

Follow Fernando Villalba in LinkedIn or Twitter

‍