Great getting started guides go to the point and evolve. Somehow the topic reminded me of bad experiences with some open source projects. With all the love towards all open source releasing devs out there, I’ve faced so many times projects in which the installation or guidance in general is too vague. Getting the app or service up and running in local machine requires a lot of hacking and solving mysteries.
Bad readme makes too many assumptions and leads to failure or giving up too easily. One of the reasons readme file exists is reproducibility. The readme file should give you enough information to replicate the process to ramp up that solution. It is quite common that good readme contains steps with code / CLI command examples. There’s something similar with readme files and most of the getting started guides. Getting started guides are part of the self-service package.
But then again those projects are most likely freetime efforts and most likely the notes in readme are for the developer him/her self. When you have commercial API product or platform it’s not the same. Then you as the provider are expected a lot more. Option is also not to give a damn, but that most likely results to bankruptcy.
In which cases do you need to offer guides?
This is important question since great guides require a lot of effort and thinking, testing and evolution. It requires resources so you don’t want to do guides “just because”. I guess your CEO (like ours) wants you to do things which takes the business forward and has value.
Anyway this question started to bother me. I would love to offer a clear rule for this but it seems impossible. At work I know that we need to provide getting started guides. Why? It’s a platform and various stakeholders are attached to it including two types of developers. It’s not as simple to get onboard fully as it would be with simple API. The variety of things you can do on the platform is huge. Connecting data to the platform or building apps on top the data provided by the platform is multistep process and it feels logical to provide guides on the critical points of the developer’s workflow. I guess workflow is the keyword here. Remember the flow state discussed previously?
Simple yes/no rule could be that
- If you want to make developer’s life easier and more productive, you probably need to provide guides
- If you have required resources (requires business reasoning), you can create guides
- If your product requires simple API call to get things done you don’t need guides.
- If accomplishing a task with your product requires multiple API calls, steps or other operations, then you most likely need to offer some guides.
Reasoning is that again you give the consumer example of expected workflow with your product and they don't need to reinvent it.
Example from Platform of Trust
An example from our platform. Let’s take the application developer. First they need to get familiar with our authentication practices (and what kind of ready-made solutions we can offer to speed up the development). They want to use our sandbox to get first smokes out of the system and learn how APIs and it all works. Then they need to register app to get production tokens and credentials for the APIs. They need to know how to find data sources. They need to connect their app to data sources via our Broker API (in the future pub/sub directly from source connector component). Application developer probably needs to use 3-4 platform APIs depending of the case.
There’s a lot they need to discover. Developers most likely appreciate if we can tell them how the normal app development process might go on our platform and offer detailed guides for key operations. We designed the process for application development on the platform and identified steps that needs to be handled. That designed process guides the internal core development as well as writing the getting started guides. At high level the idea resembles exactly what Stripe seems to offer too. I googled “Stripe getting started” and as response I got direct links to quickstart guides foor certain key points in workflow in utilizing Stripe. Vimeo has workflow oriented getting started guide as well.
Are written guides enough?
Anyway simple rule when to guide is still a mystery to me. At work we did not stop in written guides only. We decided to offer video guides as well. According to high-volume developer survey Hackerrank (2018) 1 in 4 developers started coding before they turn 16 years old. Hackerranks results support the Stack Overflow results regarding continuous learning. Even though 67% of developers have Computer Science degrees, roughly 74% said they were at least partially self-taught. Over 88% of respondents use Stack Overflow as knowledge-base on how to learn code. Youtube is the second most common (64%) and books is the third (60%). It is not a surprise that Millennials use YouTube (65%), while Gen Xers buy a book (85%). Without video content Millennials are probably not so interested about your product. But that is another story, another topic to write about tomorrow.
Entering the new area
While writing this I felt like I was entering something new. For couple days I’ve been reading research articles on video content and perception of voice. I have crossed the line now. In previous posts I’ve discussed the traditional “hard” topics of developer experience. You know, the safe bets. The topics you hear in every god damn conference. Now I’m entering the psychology of Developer eXperience. From now on technology and clear logic becomes fuzzy logic and philosophy. And I’m terrified. For the past 20 years I’ve lived with developers around me, occasionally I even dream of code. But now that familiar territory is going to be lost.
The topic of next post is a deep dive into the empathy, significance of voice, voice pitch and all human science related. That intrigues me and terrifies me. I might as well label it as the soft side of the Developer eXperience which is not technology driven, something hard to measure and impossible to convert into lines of code without human interpreter - a DX fanatic. Yeah, that’s it. I’m a DX fanatic.
Some more to read from 100 Days DX
- #100 - The biggest open resource on Developer eXperience so far
- #99 - Hackers - the top 1% of engineers
- #98 - Invalid Open API spec files ruins the developer experience
- #97 - Lightweight API evaluation framework
- #96 - Embracing open source community driven tools development
- #95 - Exploring the multilevel nature of API Design Guides
While you are here...
Check out Platform of Trust in which I've worked to enable best possible developer experience!