5 design tips for microservices developers: Improving the user experience

In this first part of a 3-part series, we explore how microservices benefit from a focus on the target audience. By paying close attention to the user experience—documentation, security, scaling, support, and standardization—developers can provide potential users with a great first look at a newly offered microservice.

Developers spend a great deal of time writing software for consumption by humans but don't necessarily consider humans in the process. I began Design 4 Developers to explore practices and patterns for creating better microservices that are simpler to test, write, and deploy. Ultimately, these practices will result in better software for humans.

In this article, we'll discuss how to align your development and deployment efforts with human considerations by using the 5Es (Entice, Entry, Engage, Exit, and Extend) to design compelling microservices developer experiences.

We'll avoid the depths of any particular technology stack and instead focus on human-centered technology needs. These needs are universal and transcend technical choices. Being aware of these needs will ultimately make you a better developer no matter what kind of work you do.

#1 Document debris

During the user's first interactions with your microservice, you want to entice them to use your service. To make sure the user has a good idea of what your service is capable of, ensure that you deliver a curated and complete getting started documentation. Some of the challenges that can be present include the following:

• A quick start that is too brief to be beneficial
• A guide that misses the beginning steps of getting started
• A wall of text that mixes operating system (Windows, macOS, Linux, etc.) instructions in one document, requiring the user to guess which command to run for their particular platform
• Missing or incorrect steps that are out of date
• Steps that only work on the developer's machine
• Requiring a user to piece together the experience from disjointed and often incomplete documentation

To address these common issues and opportunities for improvement, select a new user to test your project. Have the user try to accomplish the "getting started" steps, be ready to address any problems that arise, and most importantly, don't discount the feedback this new user gives you. This user will open your eyes to all kinds of friction, toil, and invisible work that was impossible for you to see.

#2 Security over slyness

While the user is still being enticed to use your service, you will want to ensure that you are explicit and deliberate about how your microservices handle security. All too often, security is dealt with via obscurity and/or cleverness. With our microservices, we want to ensure that data in transit is encrypted via HTTPS/TLS. If our services are protected via access tokens or keys, how often are they rotated or updated? How will our users get notifications that those keys have been updated? If the user will save data, how is it protected at rest? Finally, if our services require passwords, what are the rules around their creation and expiration, and will we support two-factor authentication? The users of our microservices deserve the security and protection that mainstream application development requires in the modern era.

#3 Scale over shatter

When developing and deploying our microservices, the users need to know how it will perform at web scale. This includes ensuring the code delivered is thread-safe, scalable as required, and lives within highly available serverless and Functions-as-a-Service (FaaS) environments. It must scale with Knative and typical container-led deployment, too. This infrastructure should be self-healing and scale to zero to conserve resources when it is not in use. The responsibility for disaster recovery and system backups should be clear to the end-user. Our users don't want to see messages about services not being available, requiring them to review log files to uncover what is going sideways for them at that time.

#4 Support over stumbling

As your target user moves closer to entering the experience, you need to curate and check your expectations of what they will accomplish. You also want to ensure they can discover that use organically, without requiring training. Your users can be on a continuum from an untrained new consumer to a well-trained and expertly drilled technical person, such as a pilot, nuclear plant, or oil drilling platform operator. Often developers are the expert, well-trained, and drilled users, and they find it hard to remove themselves from that expertise. Ensuring your users can enjoy self-service and self-start their evaluation of your microservice without any long-winded training, signups, or expensive fees will allow your services to impact as many users as possible.

#5 Standardization over straying

As your user engages with your microservices, you need to ensure you live up to the standards expected for other existing microservices. For example, using completely different access or authentication methodologies will hurt adoption and use. Consistently using camel case, labels, full words, hierarchies, and ontologies will empower the user to leverage skills learned with other services and prevent them from wasting time understanding what is required to use yours. Also, keep in mind that most microservices, while delivered as well-tested systems that do one thing really well, will live within a community of like-minded services. These microservices were developed separately but underpinned by other systems to make up a fabric or service grid. The microservices group members complement and work with each other to deliver a capability. You want to be sure that this family of services looks and feels the same and does not require a huge mental leap when invoking one versus another. Being consistent enables users to more rapidly understand the grid of services available and how to use each of them.

Conclusion

Creating human-centric software is at the core of my work. These practices, when combined, result in microservices that are consumable by your users. This provides an advantage, including fewer challenges with documentation (document debris). Keeping security and scaling in mind when deploying your services is crucial for customer's confidence. Empowering them to be successful with the first use of your service and ensuring you deliver them with standardized, consistent words and meanings ensures your users can use the services quickly and easily. These first five design tips for microservices developers provide a framework for making your users great.

This article aligns with a talk I'm giving at Red Hat Summit. To see and hear a presentation of the "10 Design Tips for MicroServices Developers" on June 15th, 2021, register for free.

Be sure to watch for the next two parts of this series, and let's keep the discussion going around the microservice developer experience.