Today I was pulled into processes. Our crew at Platform of Trust has grown and keeps on growing. Then the processes become really handy and important. I’ve not been a big fan of processes but lately I’ve found them useful. Here’s a few thoughts on those.

Guides Development Process

Our guides are written by the developers to other developers. Ẃe managers are just in the middle and removing barriers and putting some framework in place. For sketching, writing, evaluating and publishing we defined single page process for all to see and follow. Without that kind of written process the internal developer would have difficulties to understand how to proceed. The Guides are defined as tasks in JIRA (yuck!) and then we have process for development.

Now I’m almost obsolete (trying to make my role as small as possible). Scrum master and the developers can get things done pretty much without me. Of course in the end before publishing the guides to Developer Portal one of the DX/UX team reviews the guides. You need processes when your crew grows. Those just make your life easier. Don’t spend too much time with the processes though, just the bare minimum.

API Development Process

Today I spent some hours with my colleague Nazia Hasan redefining the process of API development. We had a brief meeting is which we listed things to flipboard. It was kind of pair designing. One added an item and the other added another one. We kept on saying what comes to our minds and ideas became items on the board. Above all we had fun! Can you imagine, defining a process can be fun?!

Result was 5 pages of multicolor hard to read “specs” for the process (example below). The beginning is never clear to anyone else but the people involved :) I like to do initial specs of everything by hand - either on paper or board.

Lets go for flipped (documentation first) approach

Flipped == build the documentation from customer point of view. This idea initially came from one hard core developer Viljami Kuosmanen from Futurice I’ve had the privilege to know for long time now. This flipped approach was decided already before we started writing anything on the board. We decided to define the dream process and not to take any known limitations or difficulties into account yet. Define it as we see it would be in pink unicorn filled dream land.

The principle is that we do not start from API spec file. We do not think about the implementation. Instead customer needs are added to existing API spec file which is then automatically converted to final API docs on the fly including code examples for endpoints and all. In other words spec file is used but

we define the specs from the consumers point of view - we build the docs first. Documentation is not the end of the process, it's in the beginning.

This is possible due to ready-made process for it. The process uses API spec files and we need to use it since better tools are not available. We would love to use other not so technical tool, but we have to manage what we have at the moment.

This is a topic discussed just recently in Twitter and Bruno Pedro’s blog “Non Technical API Design” too. As Pedro says in the blog, I am also forced to work with specs instead of design: “The thing to note is that most people who believe they work in API Design are actually working on technical API definition, not on designing the API from the ground up.

Anyway based on the shady sketches mentioned above I did draw more refined picture of the process during the afternoon. The details of the process was added to internal wiki (confluence).

From self-service customer requirement collection to API design

Followed by implementation, release and informing the customers

Ideally we can show the work in progress version of the API documentation with code examples before it has been implemented to every customer. Of course having a mockup API behind the whole thing would be optimal, but that is not going to happen soon. With that kind of setup the customers could try out for example new API endpoint and get the feeling of it as would be with production API (close to it).

Fake it!

In a way this is modification of fake it till you make it approach. After we have collected needed amount of testing from customers, we can push the endpoint to implementation. Now the API development team has machine readable spec of the new API endpoint, parameters needed and description so that the consumers understand them too. I would say that this is pretty solid package for the internal developer to build what is needed.


The process in a nutshell

  1. Collect the customer needs with self-service tool made for the purpose
  2. DX/UX team together with POs pick most urgent (business-wise) improvements (non-breaking)
  3. DX/UX team makes the API design by using flipped approach from eg producing the API documentation with automated tools
  4. Design is reviewed and iterated
  5. API implementation in cooperation with QA, testing and security checks
  6. Push to production, update API client package for consumers, generate the API docs from spec files with automatically tested code examples (in-house build tool).
  7. Notify customers about improvements or additional features. Remind them about the self-service feedback channel.

Work in progress

This flipped approach and the process vaguely described above is still something we tweak and fine tune. Don’t copy-paste this to your organisation - not yet :)

Some more to read from 100 Days DX