With the new release cadence of Java and vendor landscape, managing multiple versions of Java can become a tedious task. However, tooling exists to make your life simpler.

Managing multiple installations of Java on a Mac

The last few years we’ve seen an increase in various Java distributions. Now there is OpenJDK in multiple flavors (Oracle, AdoptOpenJDK, Amazon Corretto), Eclipse OpenJ9 and Azul Zing. With this increased interest in the Java ecosystem there is suddenly multiple Java distributions and versions to test your applications against. Running applications in containers is one approach, but for local development one should consider jEnv.

Installing different Java versions

First off you need to know what kind of Java distribution (vendor, JRE/JDK) you want. I personally like AdoptOpenJDK due to its community backing of known companies and ease of installation. Let’s install some JDKs!

Assuming Homebrew is installed:

Introducing jEnv

jEnv is probably the most well-known version manager for Java. It is similar to nvm, rbenv and similar project for other technologies. There is however one downside with jEnv that’s worth a mention: missing Windows support (but have Linux support).

Installing jEnv

Then add the following to your shells configuration file. For bash that would typically be ~/.bash_profile/~/.bashrc or ~/.zshrc for zsh.

Restart your terminal application or resource your configuration. You should now be able to run jenv doctor to verify your installation and see the message Jenv is correctly loaded (ignore other warnings).

An optional but recommended step is to enable a couple of plugins:

Adding Java installations

Now that jEnv is correctly installed, it’s time to make it aware of the JDK’s which we installed earlier.

jEnv is now ready for use in daily development workflows. To assign a default system-wide version use jenv global 11.0. If a specific project needs a different version of Java just use jenv local 13.0 when standing in the directory of that project. jEnv will then create a .java-version file that describes which JDK to use. This file can safely be checked in so that your whole team runs the same version of Java (if using jEnv of course).

Conclusion

Using Homebrew on a Mac, it is easy to install multiple versions of Java and manage it with jEnv. This enables experimentation with different flavors of Java and can lead to teams avoiding Java version conflicts.

Managing multiple installations of Java on a Mac

Animations can be what sets your website apart, and really makes your users happy. It shows that you have gone that extra mile to create something really special, often with great care, and oftentimes, depending on the animation, with great effort.

Unfortunately, some users may not like our animations, and WCAG specifically addresses animations with Success Criterion 2.2.2 Pause, Stop, Hide and Success Criterion 2.3.1 Three Flashes or Below Threshold. So, how do we comply?

Pause, stop and hide your animations

How to pause, stop and hide animations depends on what technique you are using.

If you are using three.js like we do on bekk.no, stopping the animation would involve creating one or more flags, and read these flags in the animation function. Changing the flags can easily be done using buttons and JavaScript, and currently that is the only thing missing on our site (PR coming in 2020 guaranteed).

If you are using CSS Animations and Transitions we can actually control animations in a few different ways. The first solution is to simply turn off animation with animation-name: none;. The effect is immediate, and not very pretty:

A better solution, especially if you expect the users to continue the animation is to use animation-play-state. Using this CSS property, the animation will pause at the current state when set to paused, and continue its animation when set to running:

When using SVG animations, the same CSS property can be applied, but you might have to add the style and control the style within your SVG in stead of in your global CSS.

Three flashes or below threshold

When creating animations, they should not contain anything that flashes more than three times in any one second period, or otherwise break the very technical definition of the flash threshold.

Given that your animations adhere to this principle, it is generally considered good practice to stop the animations, either after a given duration using animation-duration or a given number of iterations using animation-iteration-count.

Tomorrow, let’s take a look at how to automatically detect if we should limit our animations presented to our users.

CSS Accessibility - get a move on, then stop!

In functional programming we are often concerned with mathematical or pure functions - functions that do not perform side effects. Side effects are modifications of state outside of the local environment. Examples of this can be to store values in the database, fetch data from another server or alter a variable outside your functions local scope. In other words it is the very concept of things actually happening.

Image by @impurepics

When writing software in the functional paradigm are we then simply not interested in making software that solves things? Well, of course we are, but we like to know where we are impure! And we are still stuck with the broad definition of what a side effect actually is. Given advanced enough spy technology hackers can figure out your encryption keys based on the mere sound of the CPU 😱 Is then each and every CPU cycle an observable side effect we should have control over?

What a rabbit hole we got into. You probably agree that the line must be drawn somewhere. If we take a few steps back to the pure functions, then what are the properties that they have and we as programmers want?

Let us talk about the function f which takes a number x and add a two in a pseudo programming language.

We can use this function to define the following expressions:

The value of B will become 8. Do we even need the temporary expression with the value of 4? No, we can refactor it into:

This computation will have the property that B1 is equal to 8. We could substitute each usage of A with the computation that defined it. Having this property is what we call referential transparency.

Here is the same example given in the programming language Scala:

The same properties hold for this code and we can yet again substitute the usage of a with f(2) without being afraid that anything else will change. Now, what happens if our business requirements change? We need to tell our users what values get in:

Running the same statements again with the new function f1:

Between the two statements we have out commented code that shows the console output if we had run the program in a terminal. What happens if we perform the same refactoring as in the pseudo programming language?

Did you see what just happened? The computational result in b is still the same but we printed out the input to the console twice! This tells us that the println function broke the referential transparency property of our f1 function. Now we also know that println performs side effects in a way that alters how we can reason about other functions that use it.

Now we have seen the kind of side effects that we should care about. They alter the meaning of what our software does based on how they are used. Refactoring code where we have this property is simple because we can use local reasoning to know what changes that are safe to perform.

If you are unsure if a particular side effect is something that you should care about then do the simple exercise of substituting it in a way similar to what we just did above.

In this simple example this is no problem. What if this was a destructive action against the database or an expensive call to another system? It's an easy mistake to do. One effective tip is to use this tool to separate the pure business domain of our code against the parts that actually does something. Or if you have to do mutations then hide it in a function so that the users cannot observe the side effects.

But can we permanently defend ourselves against such issues? Ensure that all code is referentially transparent and perform side effects in a controlled way? Yes we can! But that's a treat for another day. Happy holidays!

Referential transparency - Or how I learned to stop worrying and love the effects

I ❤️ open source as a manager. It fills my heart with joy knowing bugs can be fixed by teams other than my own, that perhaps we're not the biggest consumer of our software and that my team can get public recognition of their hard work.

I ❤️ open source as a developer. Public code is a showcase of my skills and interests and since most easy problems have already been solved, I can concentrate on providing my unique value to the projects I care about most.

I ❤️ open source as an architect. Many cloud-ready architectures are openly being worked on by the cloud providers, forever competing on making their particular pit of success steeper and deeper. As an example, the eShopOnContainers sample contains an always updated implementation of a cross-platform microservice architecture powered by containers and services in Azure.

I ❤️ open source as a designer who knows little of design. After all, everything is a remix and the basic elements of creativity are copy, transform and combine. Open source implementations of apps or services can be wonderful sources of inspiration and learning.

When thinking of your next app, you probably start with an idea based on some existing app:

It's like Shazam, but for food.

While creating Hotdog - Not Hotdog, wouldn't it be nice to use the source of another app as a starting point? In the world of cross-platform mobile development, you have many choices to do exactly that!

For Xamarin Forms, snppts.dev has a curated collection of app starting points. From the world's simplest weather app to ridesharing or your very own streaming service, they all come with a complete source repository giving you a perfect starting point for your next app.

But most of all, I ❤️ open source as a human being. It makes me and every other designer, manager or developer more productive. We build upon the knowledge of those who came before, helping each other to not make the same mistakes and enable those who come after to start at a better place than we did. Inspirational templates help us deliver digital products faster, better and cheaper.

How will you help tomorrow's remixer?

Inspirational Templates

The modern consumer is blessed with an endless supply of products and services that address their needs. In such a competitive environment, companies need to understand the driving forces shaping consumers perception of its products and services. How else can Burger King entice modern consumers into buying their milkshake from them instead of McDonalds? Or how can Nike convince the occasional jogger that their shoes are better than a pair of sneakers with the three tilted and iconic Adidas-stripes imprinted on the side?

To make things worse, consumer perceptions can be extremely challenging to measure. If sales are increasing after a marketing campaign, it might be because of a wide range of things not related to a change in how consumers perceive the company in question. It might be caused by an increased awareness of the brand, rather than an improvement in the brand perception per se or by an exogenous event such as a competitor having screwed up.

One way to mitigate this problem is to analyze the information contained in unstructured data. Two relatively simple techniques that can be used for this purpose are sentiment analysis and wordclouds.

The first is built on the idea that matching text with a sentiment lexicon gives the data scientist insights into the underlying sentiment being expressed in a given text. “I am happy” is labelled “positive” because the word “happy” has a positive score in the sentiment lexicon.

The second technique is built on the idea that the most frequently used words in a text will tell the data scientist something about the content of the text and the corresponding sentiment. In order for this to work, the data scientist first needs to remove uninteresting words, often called stopwords, from the equation (learning that “the”, “and”, “is” and “are” were mentioned frequently in the text is probably not very interesting). Once this is done, it is relatively straightforward to create a wordcloud that will give the reader a quick glimpse into the most important aspects of the text.

The usefulness of sentiment analysis can be illustrated by the following graph. The graph shows the sentiment expressed in tweets mentioning Boeing CEO David Muilenburg, during the time period in which he testified in a congressional hearing (29th and 30th of October) about the tragic crashes of the 737 Max airplanes. A couple of interesting insights can be drawn from the graph.

First of all, it appears that the expressed sentiment is at its lowest immediately after the two days of hearings. In other words, people tweeting about the hearings while they went on were predominantly negative, and increasingly so. This insight might be used by the legal team of Boeing to adjust their strategy for the next legal battle they face, thereby increasing the likelihood of convincing the jury of Boeings innocence. Another observation that can be used in a similar way is the finding that the second day of hearings produces a lower sentiment score than the first day. Digging into the reasons for this may enable Boeing to increase their chances of winning in court in the future.

A related insight is that people tweeting about the hearing are mostly negative. In this particular case, this might not be very surprising. In other cases, however, this might be an important finding.

Third, it is very clear that the sentiment becomes much more positive shortly after the hearings. In other words, it seems like Boeing’s CEO did not make such a horrible impression after all. From a business point of view, this kind of analysis can for example be used to evaluate the lasting impact of a marketing campaign or another event that may have effects on the reputation of a company.

Naturally, as with all kinds of analysis, a good dose of critical thinking must be used when applying these techniques. That does not mean, however, that untraditional ways of analyzing data should be left unexplored.

Converting subjective data to objective data

We've covered FIDO2 in this year's eleventh calendar post, and with FIDO2 available the internet has all the tools need to lighten the load of the password. One of its results is the Web Authentication(WebAuthn) API, simplifying FIDO2 authentication for web browsers. Here are the basics to get started with a wide range of authenticators on your website.

The FIDO Alliance has since 2013 worked towards simpler online authentication and a weaker reliance on passwords. A strong alternative to password authentication is becoming generally available: the cryptographic authenticator. The authenticator covers the "Something you have" authenticator factor. To strengthen the adaption of authenticators W3C released its Web Authentication API at their "Recommended" level this March.

WebAuthn moves the burden of authenticator interaction to the user's browser agent. The API reduces both authenticator selection and communication to the two JavaScript methods create() and get(). create() is used to register new authenticators, and get() to authenticate users. Both methods accept their separate option objects to provide some level of control to implementers as well as providing the required security measures. One of these measures is the challenge. Challenges are required for all authenticator communication and serve as a nonce value that must always be signed over by the authenticator. This proves the authenticator's involvement and prevents replay attacks. The back-end services must generate and validate the challenges for it to achieve its purpose.

Registering a new authenticator:

To register a new authenticator WebAuthn exposes create(). During the registration process, the authenticator will be provided with identifiers for a relying party(the domain/server), user entity, and public-key preferences. Authenticators generate a new key-pair for every new domain it registers with, preventing a login for domain A to be valid for domain B.

Authenticating a user

When it comes to authenticating a user the process becomes even simpler. The relying party information is by default handled by the browser and the only required parameter is the challenge, again created by the relying party.

The authenticator will look up the specific private key used to register for the relying party and produce a signature for its id and challenge. To verify the authenticator the server must get the public key for the user, and check that the returned data is as expected with a valid signature.

Trusting Authenticators

In what we've covered so far, there is no verification that the communication has occurred with an authenticator and there is no verification that the authenticator plays by the FIDO2 rules. A web browser can fake the result of WebAuthn using any unsecured techniques. To improve authenticator trust there are specified rules for attestation. Authenticator attestation utilizes techniques such as X.509 certificates to build trust paths to the origin of the authenticator.

We hope this article may inspire you to try out WebAuthn If you would like to know more and see code examples check out https://developer.mozilla.org/en-US/docs/Web/API/Web_Authentication_API or the official recommendation at https://www.w3.org/TR/webauthn/.

WebAuthn - The simplest way to 2FA

If you are new to JavaScript, chances are that you might find it a bit confusing at times. This is with good reason as JavaScript is a language of many quirks packed with odd behaviors and inconsistency. Let's make JavaScript a bit less confusing by tackling one of the more overlooked quirk of JavaScript known as Hoisting.

What is Hoisting

Hoisting is something that happens during the compilation stage of the JavaScript code. Just before the code is executed the compiler scans for all variable and function declarations and allocates them in the memory. As a result, when the code is executed all variable and function declarations will be accessible at the beginning of its current scope regardless of when it was declared in the source code. This creates an illusion that make it seems like the source code has changed and that all the variable and function declarations has been moved to the top of their current scope.

Var

Let’s take a look at an example of how variables declared using var are hoisted. Consider the following code, what do you think the output will be?

If you guessed undefined you’re absolutely right. But why did we get this result? As previously mentioned, during the compilation stage the variable declaration is added to the memory, but this is only true for the variable declaration and not the actual value assignment. The compiler will only process the declaration and then automatically initialize it to undefined. The assignment of the actual value is not changed and still happens where it was declared. If we were to illustrate this using code it would look something like this:

Let and const

Let’s build upon the previous example. If we substitute var with let, what do you think the output will be?

If you guessed ReferenceError you’re right again! While let and const gets hoisted just like var there is a small difference in how they are initialized. Instead of being initialized to undefined like in the case of var, let and const remains uninitialized and does not get assigned a value before the declaration. The space between where the variable is created and assigned a value is often referred to as the Temporal Dead Zone. If we try to access the variable inside this space, we will get a ReferenceError.

Functions

Like a regular variable declarations functions are also hoisted. During the compilation stage the function declaration is read and allocated in the memory. This makes it possible to access the function before it is declared in the source code.

When using function expression, we can expect the same behavior as hoisted variables. In the example below, we try to store a function inside a var. As we know by now, when var are hoisted they get initialized to undefined. If we try to access the function before it is declared, we will get TypeError: printMyFavoriteMovie is not a function because it is undefined and not a function.

Pitfalls to look out for

Always make variable and function declarations at the top to avoid confusion.

Use let and const instead of var to avoid running into unexpected errors.

Hoisting

I alt snakket om smidig organisering, finnes det tilfeller hvor man i stedet bør drive med innovasjon på siden? Er det forskjell på store og små innovasjoner, bør vi bruke ordet innovasjon i det store og hele, og hvem bør egentlig jobbe med dette? Kaffe med Lars Kristian Flem, Hans Magnus Inderberg og Pia Solheim.

Når bør innovasjon skilles ut fra daglig drift?

If you want to follow along and complete the steps in this article you need the following tools installed on your computer:

A google cloud project with where you are the owner

The gcloud command line tools

Kubectl command line tools

Helm 3 installed

NodeJS (optional) if you want to run the application locally

You also need to enable the Kubernetes engine and Container Registry apis in GCP. The code used in this article can be found on GitHub.

What is Helm?

Helm describes itself as the package manager for Kubernetes. By creating Helm charts, we can describe all the Kubernetes resources of our application, such as deployments, configmaps, and services, in one place. A Helm chart specifies values that a user can override when deploying an application, making it easy to customize deployments across different environments.

There are three concepts you need to know when working with Helm:

A chart describes the application you want to run in Kubernetes, along with its dependencies.

A repository is a web server where packaged charts are shared. The official stable repository for example, has ready made charts for applications such as Memcached, Postgresql, and MongoDB.

A release is a running instance of a chart.

Helm installs charts into Kubernetes, creating a new release for each >installation. And to find new charts, you can search Helm chart repositories.



The Helm Docs

So, with that in mind, let's see how we can deploy a web application on GKE using Helm.

The Sample Application

To keep things as simple as possible we will deploy a simple web server that listens for requests and replies with a christmasy message. The app is written in NodeJS and creates an Express web server.

package.json:

index.js:

Dockerfile

To test the app locally run npm install and node index.js. You should now see the app running by visiting http://localhost:8000/ in your browser.

The next step is to build the docker image and push it to a container registry. We'll tag the first version of our app with 1:

Once these commands have finished you should be able to visit the container registry and see the image there.

The Kubernetes Cluster

Now that we have published the image to the registry, we need a place to run our application. To achieve this, we will create a Kubernetes cluster on Google Kubernetes Engine.

gcloud container clusters create santas-workshop

It will take a few minutes before the cluster is ready, so go grab some eggnog while the servers are spinning up.

Now that the cluster is ready, and we have pushed our deployable app to the container registry, we need to describe our deployment. This is where Helm comes in.

Creating the Helm Chart

To create a new chart run the following command (christmas-app) is the name of the chart we want to deploy):

helm create christmas-app

This will create a new folder with the name christmas-app with this structure:

For the purposes of this article we will only edit four of those files.

Chart.yaml: Metadata about our application

values.yaml: Variables for our application

templates/deployment.yaml: Kubernetes deployment file

templates/service.yaml: Kubernetes service file

The files created use the Helm Templating Language. The Helm templating language supports flow control, value templating, variables and functions.

We need to edit some of the files before we can deploy our app. We will start by setting appVersion and version in Chart.yaml to 1.

The next step is to update the values.yaml file. The values in a chart are used for user supplied values, often application specific configurations, and other values that can change between deployments. It is possible to override the values in values.yaml when running helm install or helm upgrade.

Set image.repository to eu.gcr.io/[GCP-PROJECT-NAME]/app. The appVersion from Chart.yaml will be used as the docker image tag.

Our docker image exposes port 8000, so we need to update the container specification in deployment.yaml accordingly:

Now that we’ve specified what docker image to use for our deployment, let’s package it up and try to deploy it. First we’ll run the linter:

If there are no errors we can package our deployment. This will create a compressed and versioned archive that represents our entire deployment. Neat!

To list the configurable values and their current value you can run:

Now we install our application on the cluster. christmasapp is the name of the release of our app.

To list all releases running in a cluster we can run helm ls. The output gives us a quick overview of what apps we have running, including release time and version.

We can also use the kubectl tool to check the status of how the deployment is going:

Once the pod is in the running state, let’s check the logs:

You should see the log messages created by our web server. Great! But it is a web server, so we want to be able to connect to it. The astute reader may have noticed that we didn’t create a service with a public IP address. This can be confirmed by running:

Helm is nice enough to give us the command to enable port forwarding from our local machine:

Now we can visit http://localhost:8080/ and see that our app is running. Obviously we don’t want to use port forwarding to access our app, so we will need to update our chart.

Adding a Load Balancer

First we edit values.yaml and set the service type to a load balancer.

We also need to change the file describing the service (service.yaml) by adding the target port:

Finally, we bump the version number in Chart.yaml to 2:

Now that the templates have been added we can package it up. This will create a new file with the name christmas-app-2.tgz:

Now it's time to roll out the new release. To do this we use the helm upgrade command. Note that to most Helm commands we can add the --dry-run flag to see what changes the command will create.

We have to wait for a bit until the load balancer gets an IP address. We can watch it happen with:

Once a value appears under EXTERNAL-IP, copy it and open it in the browser. You should see the message from our server!

Updating the Application

Let’s say we want to release a new version of our app that counts down the days until Christmas. We update the javascript file, build and push a new docker image:

We have tagged the image with 2, so we update the appVersion in Chart.yaml. We also need to update the chart version to 3. Note the difference between the application version and chart version. Then we package the new release:

Helm will detect the changes and create a new pod with the updated app. When the new version is ready it will shut down the old pod. This way there is no downtime for our mission critical Christmas app!

If you visit the IP you should see the updated app.

Release History and Rollback

The following command allows us to see the release history of our application:

If we want to undo the latest change, rolling back to the previous revision is as simple as:

Soon we will see the previous version of the app. By checking the history, we can see that the rollback is added as a new release. This way we have full control over our release history.

Final Comments

There is a lot more to Helm than covered in this article. Using Helm to manage apps on Kubernetes makes our applications more configurable, composable and much simpler to manage across many environment. Version management is simple, and undoing a broken release is as simple as one command.

By using private chart repositories it is simple to share charts in an organsiation. Helm can be extended with plugins to create additional features. Helm-gcs for example makes it possible to use Google Cloud Storage as a chart repository.

Note: If you created your own Kubernetes cluster, it is probably a good idea to delete it when you are done testing Helm!

Managing Apps on GKE Using Helm

On the JVM, calling a function or instantiating a class will always incur an overhead, unless the JVM runtime performs some magic. At least, that's how it used to be before Kotlin introduced the inline keyword. This article will give you a quick introduction to this fantastic keyword, and how it can help you!

Inline function

Say we have an extension function for finding one element in a list of strings which has some specific length.

Yes, this is a simple and contrived function for this use case, but it illustrates the point.

The function will be compiled into a static function as part of a final class, which will then be called at the call site. Now, say we have some hyper-optimization to do(no, the JVM will not inline for us at runtime for.. reasons 🤷‍♀️ ), so we simply cannot accept the overhead of the function call! Enter, inline.

By adding the inline keyword to the function signature, the call to findStringOfLength will be inlined at the call site by the compiler. In essence, it copies the code of the findStringOfLength function, and replaces any findStringOfLength call with the code in the function body. Neat! However, if you copy this simple sample code, you'll get this reminder from the compiler;

Expected performance impact of inlining 'function definition' is insignificant. Inlining works best for functions with parameters of functional types

So when might this be usefull? 🤔

Higher-order functions

In the Kotlin standard library, there is a cornucopia of extension functions which make our lifes easier. One example of such a function is the any function, a higher-order function which is callable on anything Iterable. By the help of Intellij, here's a definition and sample call.

any acceptes a function argument called predicate and calls it on each element in the list. If the predicate returns true for any element, the any function will also return true. Now, if any didn't have the inline modifier, this would mainly have two consequences;

The any function would be called as a static function

Any Lambdas passed as arguments would be compiled into a generic function object at each call site

So, if we're only passing regular functions to any, there isn't that much overhead. But we pass Lambdas, don't we?

This reveales another effect of the inline modifier - Lambdas which are passed as arguments are also inlined! 🤯 So by passing Lambdas to an inline function, we avoid both the runtime costs of the static version of the inline function, as well as the generic function object of the Lambda! This is one of the many reasons that Kotlin can maintain performance on par with Java, while extending the Java library with modern concepts.

noinline

While inlining of lambdas is great in most circumstances, there are times where that's not desired. In that case, just annotate the function argument with noinline.

Non-local returns

Lambdas are allowed to use the return keyword with a label, e.g. return@forEach. When the lambda is used as an argument to an inline function however, the return keyword will act as if it was a return used in the function body of the enclosing function. This is a small but neat trick that makes an ordinary extension function seem as if it's part of the language!

crossinline

Non-local returns can be great, and makes the Lambdas feel like a natural part of the language. However, there might be times when this kind of functionality is not desired, such as when passing the lambda to another function. To deny this behavior, just add the crossinline keyword to the argument.

Generic functions

Another usecase is generic functions where you need access to the actual type of the generic parameter. Normally, generic functions does not have access to the actual type of a generic parameter, as the generic type is erased at runtime. With an inlined function however, the function will be executed in place where it still has access to the type. Just add the keyword reified to the generic type!

For more information, see day 15 of the Kotlin Christmas calendar.

Inline class ⚠️

An experimental feature of Kotlin is inline classes.

These classes can only have one actual property(as declared in the constructor), and no init block. While this sounds like a somewhat amputated class, the power comes when the code is compiled. The compilator will prefer to erase the inline class, so source code which deals with the Name class, will (mostly) see the String class after compilation. This has some key benefits;

The overhead incured when using the inline class is comparable to other primitive wrappers such as Integer and Boolean, so minimal

The optimizations related to primitives(e.g. Long or Floats) are used

The ability to have stronger type safety on properties

As an example, see the following two data classes;

When you use the Employee class, it's easy to accidently swap the salary and age arguments. With EmployeeWithInlineClass however, you have to instantiate the arguments with the correct type, forcing you to send in the right value to the right argument. This is of course nothing new, as one could use a regular old class before, but that would guarantee an overhead! When an inline class is compiled on the other hand, the compiler will prefer to erase the inline class as much as possible and stick to the primitive wrapped. This will yield better performance when compared to using the tradition class, while providing the same type safety, which again can lead to fewer bugs. For more on inline classes, see this post on the Kotlin Expertise Blog.

Overhead from calling? Not with inline!

En liten historie om hvordan produktteamet vårt prøvde seg frem for å finne ut hva vi ville få til. Hvordan vi jobbet frem noen ambisjoner og strevde med å finne gode måltall. Litt om hvordan vi måtte tenke noen hakk større enn vi var vant til. Og litt om at det ikke var lett.

Vi var et nytt produktteam. Det vil si, før sommeren var vi et prosjekt med tydelige rammer, forventninger og budsjett. Vi mottok en overordnet plan en gang i halvåret som sa hva vi skulle lage, og målet var å få til det på en god måte. Men så ble vi et produktteam. Ingen sa lengre: dette skal dere lage. Hvordan skulle vi starte? Vi ønsket å jobbe på denne nye måten. Så absolutt! Men vi visste ikke helt hvordan. Vi trengte en retning, og det var også andre rundt oss som trengte å vite hva vi hadde fokus på.

Vi var et tverrfaglig team på fem som jobbet på NAV med arbeidsrettede digitale verktøy. Tre utviklere, en produkteier og meg: en UX-designer. Vi levde i en "kontinuerlig utviklings"-verden. Vi hadde svære applikasjoner ute i prod som skulle forvaltes og bli bedre. Vi skulle nok fortsette å jobbe videre med de, og kanskje skulle vi lage noe nytt. Det var masse vi kunne ta tak i - men hva var viktigst å ta tak i først?

Vi prøvde det ut på denne måten

Vi ble inspirert av Lean Canvas, Business Model Canvas, OKRs og presentasjon fra Finn.no om ambisjoner og mål. De ulike elementene vi jobbet med ble ambisjon, problem, verdi til bruker, verdi til organisasjon og hvordan måle at vi oppnår denne verdien. Dette ble en tom mal med diskusjonspunkter, og ble etter hvert kalt ambisjonskanvas. Håpet var at dette kunne skape et grunnlag for arbeidsmøter for å hjelpe oss å komme i gang med de viktige og riktige diskusjonene rundt hvor vi ville, hva vi skulle prioritere og hva vi ville oppnå.

Hvorfor skulle vi ikke snakke om hva vi skulle lage?

The Design of Everyday Things - Bok av Don Norman. Illustrasjon av Anca doodles

I vår bransje bør målet aldri være "å lage noe". Å ha laget noe gir ikke verdi i seg selv. Et nytt produkt er ikke automatisk et nyttig produkt. Se for deg den fantastiske tekannen som er bokomslaget på Design for Everyday Things av Don Norman. Her kan en tenke at noen hadde satt seg målet om å lage en tekanne. Og så laget de en tekanne. De oppnådde målet. Det kan ingen si noe på. Men var det nyttig? Vil brukeren av denne tekannen kunne bruke den? Var det riktig å bruke tid på å lage noe som ingen trenger?

Prosessen vår (noe forenklet…)

Vurderte ambisjoner og problem: Hva ville vi oppnå? Hvilke problem var viktig å løse?

Hvilken verdi kunne vi skape for både bruker og organisasjon?

Prioriterte ambisjonene. Satte ett fokus!

Fant måltall. Hvordan kunne vi vite at vi gikk i retning av ambisjonen?

Hvilke tiltak skulle vi gjøre for å nærme oss ambisjonen? Idémyldring. Lage hypoteser, prodsette, teste og lære.

Først bare ambisjon og problem

I arbeidsmøte med alle i teamet snakket vi om hva vi ønsket å oppnå. Dette ble ambisjonen. Vi valgte å bruke begrepet ambisjon fordi mål, målbilder og verdiforslag hadde folk i organisasjonen og teamet så mange ulike assosiasjoner til allerede. Ambisjon var et fint begrep som ga oss noe å strekke oss etter.

Det var tydelig for oss at det ikke var vits å snakke kun om ambisjoner hvis det ikke fantes noe problem det var verdt å løse. Så på første arbeidsmøte hadde vi fokus på både ambisjon og problem. På forhånd ante vi ikke hvor mange ambisjonskanvaser vi kom til å ende med, så vi holdt antallet åpent og jobbet med flere på en gang. Vi bygget dette på eksisterende brukerinnsikt, domeneinnsikt og overordnede mål i organisasjonen.

Å konkretisere en ambisjon på riktig nivå var veldig utfordrende. For vi elsker jo å snakke om løsning. Det er jo det vi er gode på! Vi er problemløsere som lager ting.

Så hver gang noen begynte å snakke om hvordan vi skulle løse dette, gjentok jeg disse spørsmålene i ulike varianter: "Hva ønsker vi å oppnå?". "Hva ønsker vi EGENTLIG å oppnå?". "Hva vil det gi av verdi til brukeren?". For å fange essensen av det vi snakket om. Samtidig parkerte vi tanken om løsning på en lapp. Det var jo ikke det at det var uinteressant. Det var bare ikke nå vi skulle diskutere hvordan. Vi skulle ha fokus på hva vi ønsket å oppnå i lengden.

Et stort nok problem

Vi trengte å tydeliggjøre hvilken situasjon vi ønsket å gjøre bedre, og for hvem. Problemet var ikke på et detaljert, brukergrensesnitt-nivå, men på et overordnet nivå. Et problem som var stort og viktig nok.

Noen av problemene vi diskuterte var antagelser vi hadde hørt i organisasjonen eller vi hadde selv, og andre problemer visste vi om fra brukerinnsikt. De problemene som var antagelser visualiserte vi tydelig ved å skrive store spørsmålstegn på. Det gjorde vi fordi at det ikke skulle bli sannheter, men minne oss på at dette måtte vi ta tak i og utforske senere.

Verdi til bruker og organisasjon ble likestilt

Hva er det ambisjonen forteller noe om? Er det hva vi skal oppnå for bedriften? Eller for brukeren? Jeg opplevde det som kunstig å skulle velge mellom disse. For oss føltes det riktig å få med begge perspektivene når vi snakket om ambisjonen. Hvis vi når vår ambisjon, hvilken verdi vil brukeren oppleve? Og hvilke gevinster ønsker vi å se for organisasjonen? Begge disse aspektene inkluderte vi i teamets diskusjoner.

Prioritere ambisjonene

Etter arbeidsmøtene der vi gikk bredt ut og jobbet med flere ambisjoner og fokus på en gang, var det på tide å samle oss. Alt var jo så viktig! Hvilken ambisjon skulle vi jobbe med først? Vi måtte prioritere ambisjonene. Gjennom litt dot-voting, diskusjon og tenking gikk vi for ett fokus. Én ambisjon.

Hvordan kunne vi vite at vi nærmet oss ambisjonen?

I teamet har vi jobbet hypotesedrevet i cirka ett år. Det innebærer at de løsningene vi har gått for har vi formulert som hypoteser, som har blitt testet og vi har lært om antagelsen om løsning faktisk løste problemet. Mer om prosessen rundt hypoteser

Men det var jo også bare antagelser at de forskjellige løsningene vi kom opp med, faktisk førte til at vi nærmet oss ambisjonen. Vi burde kunne følge med på om vi gikk i riktig retning. Derfor var det behov for målinger. For å ikke forvirre og blande dette med mål, så brukte jeg begrepet måltall. Hvordan kunne vi vite at vi nærmet oss ambisjonen? Hvordan kunne vi vite at vi skapte verdi for brukerne og organisasjonen?

Måltall

Å faktisk klare å finne gode måltall og få de på riktig nivå var skikkelig, skikkelig vanskelig. Vi måtte prøve oss frem. Det må også nevnes at når vi jobbet med måltall så var dette ikke ferdig i en workshop på to timer. Det ble mange iterasjoner! Vi jobbet med dette over flere uker der vi også jobbet med konkrete løsninger innimellom. Det ble tett samarbeid mellom meg og utvikler. Mye graving. Mye refleksjon. Og vurderinger. Vi laget et eget dashboard til ambisjonen der vi kunne samle måltall fra ulike kilder på én side.

Noen målinger på løsning og noen på ambisjon

En ting vi erfarte var at å finne det riktige nivået ble enklere når vi fikk et tydeligere skille mellom ambisjon og løsningshypotese. Måltallene koblet til ambisjonen skulle ikke måle om de konkrete tiltakene en nå jobbet med, funket eller ikke. Fordi disse målingene skulle kobles til løsningen og hypotesen. Målingene på ambisjonen burde være en slags helsesjekk som vi kunne følge med på i løpet av flere måneder. Uavhengig av hvilke idéer vi gikk for, så burde måltallene gi oss en pekepinn på om vi gikk i riktig retning.

Ikke la målingen ta overhånd

Noen ganger var vi veldig fokusert på å finne de gode tallene, men fikk det ikke helt til. Vi stanget hodet i veggen, og en tanke streifet oss: skal vi la være å fokusere på akkurat denne ambisjonen nå? Vi klarer jo ikke å måle det…

Da måtte vi stoppe opp! Tenke på hvorfor vi jobber med disse målingene. Det er jo bare et hjelpemiddel. Selvfølgelig skulle vi fortsatt designe og utvikle det vi tenkte var det viktigste. Og om vi ikke kom på noen geniale måltall før vi lanserte, så kanskje vi kom på noe senere, når vi fikk øvd oss mer på dette.

For uansett: måltallet måtte aldri bli målet i seg selv! For det kunne virkelig gått hardt utover brukeropplevelsen hvis vi skulle optimalisert tjenesten for å få til et godt måltall.

Helt tilslutt...

Dette har vært en liten historie om hvordan vi i høst prøvde oss frem med ambisjoner. Og vi prøver oss fortsatt frem. Vi jobber videre med ambisjonene. Prøver fortsatt å finne noen gode måltall vi synes det er interessant å følge med på. De måltallene må følges med på jevnlig, analyseres, forstås og om vi oppdager noe spennende så må vi agere på det. Kanskje blir konklusjonen etterhvert å si: dette er godt nok, la oss sette fokus på en annen ambisjon. Eller skrote en ambisjon. Eller lage en ny.

Denne historien har ikke handlet om hvordan disse ambisjonene også ble formidlet videre til ledelse og brukt i budsjettforhandlinger. Den historien får bli en annen gang.

Ambisjonskanvaset - bruk det som utgangspunkt for diskusjon

Ikke bare fyll ut malen!

Det gjør litt vondt å dele malen til ambisjonskanvaset i dette blogginnlegget. Rett og slett fordi den ikke er viktig! Det er ikke viktig å fylle ut noen mal, for det har ikke noen verdi i seg selv. Det som var viktig var at teamet fikk diskutert hva vi ønsket å oppnå. Det var ikke lett, og for oss hjalp ambisjonskanvaset oss til å styre diskusjonen bort fra løsning og inn på hva som ville bli riktig både for brukeren og organisasjonen.

Prøv det. Det er ikke lett.

Vi har ikke landet hvordan vi bør gjøre dette. Dette er sikkert ikke den beste måten å jobbe på. Men det ble denne vi prøvde. Og prøver. Og det er det jeg vil avslutte med: prøv. Vi har bare prøvd oss frem. Det er skummelt. For alt har ikke blitt riktig. Og det er lett å kritisere. Vi har prøvd én måte. Så har vi tenkt litt. Prøvd litt mer. Lært litt. Lært mye. Og prøvd litt til. Det er ikke lett å finne gode ambisjoner for teamet. Det er ikke lett å bytte mellom fokus på ambisjon og fokus på løsning. Det er ikke lett å vise til andre deler av organisasjonen hvorfor vi jobber på denne måten. Det er ikke lett å sette av tid til dette i hverdagen. Det er VIRKELIG ikke lett å finne gode måltall som sier noe om vi er på riktig vei eller ikke. Det enkleste hadde vært å bare ta tak i backlogen vi har, og jobbe oss gjennom den. Men det betyr ikke at det hadde vært det riktige å gjøre.

Ambisjoner og måltall: hvordan vi jobbet med å finne teamets retning

Having great documentation is what differentiates a great library from an ok one. I've spent the last couple of months creating a design system and its documentation site in Docz, and I'd like to share some experiences.

What's a docz? 🤷‍♂️

Creating a documentation website is a lot of work. Well, at least it used to be. You had to set up a build system, preferably with some kind of hot reloading for a good developer experience, server side rendering for searchability and interactive examples for, well, fun.

Docz is a flexible all-in-one solution that lets you get started with what's supposed to be the fun part - documenting whatever you've created.

Below the hood, Docz is basically a Gatsby page with all the plugins you need to create magic. It adds support for MDX, props parsing and a ton of other stuff - all hidden behind a single dependency.

How to get started

To get started, create a new project, and install docz via your favorite package manager. You'll also need React and the prop-types package:

Now, you can start your app by running yarn docz dev. Voila - you have a running example app!

Next, create some components. Let's create a src/Button.jsx, because everybody makes buttons in these example articles 😄

It's a pretty simple component that shows a spinner if the isLoading prop is true, otherwise the children prop. Just to be fancy, it comes in primary and secondary variants as well.

Next, let's create a MDX file that documents this button! You can place it wherever you want, but perhaps right next to the component would be a good spot?

If you're not familiar with MDX, it's basically Markdown with JSX support. You can render React-components directly inside of your Markdown, which triggers some really cool possibilities. You can read more about MDX at its website if you're interested.

Each MDX file starts with some YAML-configuration fields called frontmatter. We specify the name of the page, and the route it should be mounted to, and then we start creating our document!

MDX allows for imports at the top, and this is where we import the component we want to document, as well as a few helpers from the docz library itself.

This is how it looks:

Looks fair, right? The mix between JSX and regular Markdown is a bit weird at first, but I promise you'll get used to it quickly.

The <Props /> component accepts an of prop, where you pass in the component you want documented. This creates a UI where the prop types of your component are parsed and shown in all their glory.

The <Playground /> component lets you create live demos of your component, which the user can interact with.

If you want, you can create stateful components directly inline!

This is incredibly powerful, and since it's just React, you can create really complex examples that shows real-world usage in a simple and straight-forward way.

Typescript? One line.

Docz is written in Typescript, and has built in support for parsing Typescript type signatures. All you need to do is to create a .doczrc.js file with the following content:

That's it! Now we just need to rename our Button component to Button.tsx and change the prop types into a type signature!

We can reload our app, and everything should work just as expected. That's pretty slick!

Document your components with jsdoc

Even though you're probably following all best practices when it comes to naming, some props just need a bit more explanation. That's where JSDoc comes in. JSDoc is a way to write comments in a standardized way that we can parse with other tools. Here's their website, if you want to have a look.

Let's add some explanations to our types!

When you refresh the page, you'll get even more details out of your <Props /> component.

Make it your own

These "all in one docs site" projects are nice and all, but they're not much use unless you can customize them to fit your usecase. We're creating a design system, and the site should probably be created with those components instead of the built in ones.

Luckily, Docz is built with Gatsby, and includes Gatsby's number one power feature, component shadowing.

If you want to create your very own design, for example, create a new file src/gatsby-theme-docz/index.tsx and build your own! If you just want to change the logo - shadow the src/gatsby-theme-docz/components/Logo/index.tsx file.

For most open source projects, however, you can get away with just tweaking the original design. You even have light and dark theme support by default, and you can tweak the colors to fit your brand.

Real world usage - how has it been?

We started using Docz in an early v2 release candidate, but it's been a pleasure to work with as it has matured. We've rarely been stuck, and we've created some pretty advanced customizations so far.

To be honest, the only issues we've run into so far has been related to the react-docgen engine that parses the jsdoc and Typescript types to feed the Props component with prop data.

You can check out our design system site if you want - just note that it's in Norwegian 😱 We're really happy with the result, and we're looking forward to continuing using Docz in the future.

16-Dec

Today's posts