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:
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)
- Let the manager define target and some of the fundamental requirements from DX perspective, handle the business side of ordering and then kick him/her to vacation. In other words manager should trust the experts that they can get the job done.
- Another thing is to ensure fluent communication between all the participants. In this case inviting all participants including subcontractor to our slack in private channel worked well. Private to ensure that they can focus on team work and others stay away from asking stupid questions.
- Third thing was to order results and not to buy development resources from subcontractor.
- Fourth thing was to accept that this might fail and we would find out that the value gained would not be big enough. This “liberated” the team to experiment freely and go towards the best possible solutions without fear.
- Fifth, We also gave the main developer (subcontractor) freedom to choose programming language instead of dictating that he must use Python. Of course we discussed the language selection, but the developer used the one he’s most comfortable with.
- Sixth, aim for 80% solution, accept that this will NOT be production ready at the end of 1st development phase.
- Seventh thing was that good team will go beyound your expectations.
- Eight, keep the scope of development small. Aim for improving one aspect of the whole. In other words use iterative development.
- Ninth, timebox the effort.
- Tenth, it was a challenge developers liked. It would create automation to the internal DX and it was intriguing to see if it can be done without enormous efforts.
- Lastly. In my opinion we got the best talents in the team mostly because there was time due to slow development otherwise.
Some more to read from 100 Days DX
- #85 - Great Developer eXperience requires fluent internal workflow
- #84 - Theory of Economics of Developer eXperience
- #83 - The Space of API Design Decisions is missing
- #82 - Purpose of API Evaluation Framework
- #81 - Should We Move to Stack Overflow?
- #80 - Four data driven ideas for improving API documentation
While you are here...
Check out Platform of Trust in which I've worked to enable best possible developer experience!