loading...
Cover image for Delivering a good Experience as a Developer

Delivering a good Experience as a Developer

pierremouchan profile image Pierre Mouchan Originally published at Medium ・8 min read

Quick note: This is my first article, aiming to warn new developers in the industry and giving a small refresh to all developers! I wrote this one using my experience and some other sources that I will link at the end. Enjoy reading!

“No product is an island. A product is more than the product. It is a cohesive, integrated set of experiences. Think through all of the stages of a product or service—from initial intentions through final reflections, from first usage to help, service, and maintenance. Make them all work together seamlessly.”
— Donald Norman

"Make them all work together seamlessly", said Donald Norman inventor of the term “User Experience” and professor in cognitive science in the ’90s at the University of California in San Diego. We should know, as developers of any kind, that our mission is to deliver a decent user experience. No matter what (and we will talk later of this “no matter what” again), we have to deliver something solid, something fast and something that can be easily understood and used. This is primarily the job of UX Designer to ensure that our app/website got a good UX but we, as developers, are also responsible for it and we need to make sure it works well.

Example of bad UX implementation.

User Experience (UX) and Developer Experience (DX)

Okay, okay slow down… Let’s defines both of them before diving into the real subject. We often hear about user experience and we should all be aware of this term.

User Experience

User Experience (UX) is really hard to explain… Simply because it means A LOT, and regroup A LOT of things. User Experience is a middle between “User Interface Design” and “Usability”. UX design, like I said cover a vast array of areas. UX design is a long, long process than even begins before the app is in the user’s hand.

Developer Experience

Developer Experience (DX) is quite a new term in the industry. It is greatly related to UX in a sense, and clearly self-explanatory — "The experience lived by developers.” On the other hand, DX is related to some services especially made FOR developers (the targeted audience).

Let’s take Stripe for example (an online payment platform), its usability is quite interesting. How can you know that this service respond to a DX and not an UX? So … you create an account, you log in, you go on the dashboard and BOOM, WOO, Stripe gives you a secret token, Webhooks, a DEVELOPER TAB in the navigation and an API Key?

An API what?

Stripe gives you directly “developers-only” information and doesn’t hide these options and settings in a subdomain like api.stripe.com. It’s why a “non-developer” person will be scared by this weird information and will be less tempted to use this online payment service, while a developer would be in paradise.

A good counterexample is Mailchimp (a marketing platform used to manage mailing list, newsletters and campaigns.) Unlike Stripe, Mailchimp hides the “developers-only” information in a different page. Mailchimp isn’t MADE FOR developers (even if developers can use it easily), their main target audience is marketers, which will not have trouble using it and will not be scared by weird developers stuff.

Have you already seen a random guy using Codepen or AWS? Seriously? Hope you understand the difference now. :)

Mailchimp and Mailchimp developer differentiation.

Internal Developer Experience?

In the previous section, we define the experience that our products as developers should provide. These experiences remains, in a way, totally external, we provide an experience (UX or DX) for a specific external target. We should not forget that we are using the product too (yes, really!) We are touching the internal code of these future applications, so we are using them also, it is logical, right? For me, it’s a complete different branch of the experience that I like to call the Internal Developer Experience. They may sound complicated to understand by now, so l will take an example.

John to the Rescue

John is graduated from a marketing school, he was always a smart person and, as the tech industry arise, think that he should learn how to code. So he spent like 5 months taking courses over and over about HTML CSS and JS stuff to get his first job at “Lorem ipsum Agency” as a Front-End Developer. John never worked in a team before, he was just taking these courses online on “How to build a TO-DO list in HTML” (Please stop building to-do list guys, please…). John’s first mission was to build a website for a future industry with a navigation bar, a video player and a gallery. No problem for John, he made it successfully without any issue. He finished his website in time and the website is working, has a great User Experience and good performance for a new and fresh developer in the company.

(Until then, no worries, we agree?)

John, proud of his work.

… then Sarah came

Next week, Sarah, another developer of “Lorem ipsum Company” had to develop a contact module on john’s website. So, Sarah opened his favorite code editor, clone the repository of John’s website and, and……
She was completely lost, she didn’t understand any lines of code of john’s website, and the folder structure of this project was completely a mess!
So, john had to take 5 hours to explain each file and function to Sarah, they lost a total of 10 hours of work (2 * 5 hours) and made “Lorem Ipsum Company” lose money and time.

Incomprehensible code.

The real question is: Why and How John passed a bad project to Sarah?

(Do you begin to understand where I’m going with the “Internal Developer Experience”, wait a minute, I will explain it in detail.)

This is a schema representing the time spent by John working on his website.

Time spent by john working on his website.<br>

But … something in this schema is missing, something crucial is missing in John’s website. John does not understand why Sarah can’t work on it. John forgets about the “Internal Developer Experience”, he forgets about the best practices in terms of “working in a team” and that his code should not JUST be readable by himself but by ANY developers.

So let’s take a look at John’s timeline and let’s correct this. Here is what john should have done with his project.

Corrected timeline.<br>

What a complicated timeline? Isn’t it? How can John do two things at the same time? And firstly, what’s documentation and refactoring?

Let’s start with the beginning, definitions.

Code refactoring is the process of restructuring existing code into a more “readable” and often more “performant” of this code while preserving its functionality. Refactoring is intended to improve the design, structure, maintainability of an existing code source while creating a much cleaner, less complex and a more architectural version of it.

Code example which isn’t refactored nor documented.

We extract and group the logic in an external function (ordering the code).

With some little refactoring session, John would have delivered a better experience to Sarah, right?

Can he do better than that? (Answer: always!)

Documentation is documentation, seems pretty obvious, but what does it mean for a developer?

We have to comment our code in order to be understood—That’s all

It sounds simple? Written good comments is hard, it takes time, sometimes you know what you are doing, but you have difficulties to explain it, or to be sure to be understood (myself included). You have to be explicit about WHAT the code does and HOW it does it.

Last advice:

  • Your documentation needs to be ready at any time, be sure not to do it the last day. Example: you get sick Monday and the delivery is Tuesday, I hope someone in your company can work on your project!
  • Don’t over-document: The code may be self-explanatory sometimes. You should have good quality and minimal documentation in your source code.

Documentation has to be part of our job as developers, you have mainly two cases where you NEED to document it:

  • The first one: The case of John and Sarah, you have to pass a project to a colleague, your code needs to be enough documented to be understood by others than yours. It seems logical, since the other developer is not in your head and not behind you when you are working in your company (I hope), he can’t completely understand the “way” you developed the project.
  • The second one: Imagine working on a website, everything is fine again (like John’s case). One year pass, and you have to get back on this project and make adjustments on a module that you made 1 YEAR before… And you know what? You don’t understand any lines of codes! Good luck … and document it this time!

I could have made a full article on just “refactoring” and “documentation” but this is not the main purpose of this article (maybe one day), I let you google these terms if you are looking for more information.

Even if these two methods sounds like an obligation, we often tend to forget the cons that comes with the pros:

PROS:

  • The code is more readable, simpler and cleaner.
  • We ensure that we are going in the right direction when we are coding and adding comments at the same time (to know what we are doing).
  • Passing the project to another developer is not a pain (on both sides).
  • You could save money, time and headaches !

CONS:

  • If the code changes, you have to changes and correct the comments (nearly ever done).
  • It takes times, refactoring and documenting your code isn't free. It cost you time and so money.
  • If you have a short deadline, you would sometimes have to neglect the 'refactor'. Deadlines come before UX / DX and Internal Developer Experience unfortunately.

Summary

Did you remember ?

"...Think through all of the stages of a product or service – from initial intentions through final reflections, from first usage to help, service, and maintenance. Make them all work together seamlessly." — Donald Norman

“From first usage to help, service, and maintenance.” “Maintenance” here refers directly to what we talked about (Internal Developer Experience).

Today, I wanted to separate these three topics (UX/DX/Internal Developer Experience) but they are in a way all linked together. I hope you understood the importance of them and you will apply them in your future projects. Again, documenting a project is hard, it takes times, but the benefits are worth it.

They are all made to ensure the future of an application / website.
UX and DX for growing and keeping the users base and the Internal Developer Experience to ensure the maintainability and the evolution of it.

Oh, one more thing!

You can follow my adventures on social networks! 🚀

You can find my social networks bellow next to the“Follow” button, which you should have already clicked! 😎

Sources: https://developerexperience.io/practices/good-developer-experience

https://css-tricks.com/what-is-developer-experience-dx/

https://en.wikipedia.org/wiki/Code_refactoring

https://blog.submain.com/how-to-document-code/

Posted on by:

pierremouchan profile

Pierre Mouchan

@pierremouchan

I'm Pierre Mouchan, a (French) Freelance Developer and Entrepreneur. 👨‍💻 I post advice, tutorials, thoughts and works on web Development / Design and Growth. 🚀

Discussion

pic
Editor guide