As I’ve mentioned in yesterday’s post API documentation is something we find important at Platform of Trust. Reason is simple, flawed API Docs is the most common reason to ditch any API.

Let them experiment

During summer 2019 I had vacation coming and I would be away for a month. Summer time is always a bit slow on development since most of the management goes for earned holidays while some of the developers remain working. I wanted to do a small experiment, I wanted to give something interesting for the developers to work with. I knew that we need a small tool in API documentation process to automate code example generation for multiple APIs which naturally have multiple endpoints and methods. All the APIs have RAML specifications and that should be used as source for code generation.

Get it started and get out of the way

I had a company in mind, a subcontractor (Frostberry) I have never used before. I also wanted to test them :) So I wrote initial requirements and pushed those to Tech team lead for review. After a few rounds we have joint understanding of what we want. We saw that the implementation might be hard or the result might be too cumbersome to use. But we wanted to explore the idea. Thus I asked a quotation from the subcontractor.

Before they gave me anything back, we had online meeting and we discussed some more. After that discussion fixed price and timeline was given and contract was signed. We all knew and accepted that this experiment might not succeed and it would be mostly wasted time and effort. Well not completely since we would learn why it would not be a good idea to have this kind of tool. In short, one of the goals was to learn by doing.

I collected all participants to our Slack and created dedicated channel for the experiment. We did not use any other communication tools than Slack discussion, Slack calls and code (github). After the kickoff I started my vacation and left the team working.

More than I expected

I came back from holidays and collected people for demo. The result was a surprise. Not only had they done the easy to integrate code example generation tool, but also validator for the generated code. They had also created capability to execute the generated code to see that they actually work. That was possible because we have open sandbox environment which has same APIs as in production. Also our API documentation is build to use sandbox.

The QA people had raised an interest towards the tool too. They found use for it in crafting the testing suite for our APIs. In short, the team had really let loose and I would assume that a few flow states was experienced based on the results. The results provide value for the internal DX (automation) and external DX (better and working code examples in API documentation). We can run the process automatically every time any of the RAML sources change and get the latest API docs out.

The result is released as open source in Github under Platform of Trust:

Retrospective

I asked the team why this small project was a success. I askead “What kind of reasons you see that made it success? What could have gone better?”

The reason why I think it was a success is related to what the tool actually does: it automates the process of keeping the documentation in sync. This is both a process that is very important for an organization, but at the same time highly unappealing to developers, and most of time not critical / lower priority. From a development perspective our awesome developers (as well as Sven) did a great job (scrum master involved in the development).
it was an interesting task to work on and not a chore which almost always results in a more inspired developer and better implementation. (main developer, CTO in the subcontracting company)
not much to add to the thoughts already mentioned. Well done everyone! When I returned from vacation this was already somewhat finalized. (QA lead)
I would notice that we had a great communication during implementation stage and it was a key point to achieve success. (test engineer)

Lessons learned

Some more to read from 100 Days DX