Developer Experience Starts with Documentation

The Pain of Bad Documentation

Imagine this for a moment, you're a developer at a company working on an online digital solution. Management have decided to purchase a new product and you've been instructed to integrate it. After taking a long hard look at the documentation, you contemplate a change in career. Reems of text, example code with no descriptions, barebones payload examples with no explanation of fields, no language examples. It feels like work to understand the documentation even before you can understand the product itself.

This experience of frustration easily put developers off and creates a bad taste. Tough luck for the developers at the company who have already signed up to the product. What about companies who have tasked developers to create a POC before deciding upon one? Is it obvious how this can make or break a decision? The decision between a sale or outright rejection because the developer didn't manage to create a sufficient POC? The all singing, all dancing sales & marketing routine which seals the deal but falls flat when the real work begins. Some vendors treat their documentation as an afterthought.


A Different Experience with Storyblok

Thankfully, I didn't have this experience with Storyblok 's documentation. In fact it was quite the opposite. This article isn't a sales piece to try to convince you to subscribe to the Storyblok's product. I'm not a salesman; I'm a developer and an architect. When looking at a product/service I don't buy into the marketing speech, I need to understand how the product ticks before I'm pressed to give any impression. So as any developer would, you go straight to documentation. For most developers, this is their home page. The goal is to understand the product as quickly as possible. How easy is it to use? Will it work against the programming language I specialize in? Does it fulfil the business's requirements? What are the integration touch points? What are its use cases? Is the developer happy to work with the product? The answer to these questions forms the basis of the impression which get fed back to the potential customer. How quickly can we get design documentation to give the developer an impression as quickly as possible.


First Impressions: Startup Guides

Without sensationalizing it too much, I was blown away by Storyblok's start up guides. See the choice of frameworks? It's the first choice you're asked to make before you even touch Storyblok. Already you are being told that you can use Storyblok with ANY of the major JS based frameworks. It's practically screaming in support of developers. Each JS framework has a Storyblok package that more or less follow the same pattern as its counterparts. The pattern concepts and architecture are the same, so no matter what framework you use, the experience is the same. Any developer with some experience under their belt can have a functioning POC with a starter Storyblok instance up in less than an hour. By this time you will have learnt how easy it is to pull content from Storyblok and render it on your POC site. The quick start guides are kept up to date with the latest JS framework upgrades.



https://www.storyblok.com/technologies




Documentation Beyond the Basics

If Storyblok can spend the time and resources making the best tutorials and documentation it possibly can...imagine what the product itself can do? I often see product teams create fantastic software but then don't spend the effort to document. The documentation team at Storyblok makes great effort to ensure you can get started with no hurdles. You get the impression that the product (as developer or marketer) is very easy to work with.

As you dive deeper, you realize this also propagates to the rest of the documentation touch points. Tutorials extend into real-world use cases that help developers understand how the platform fits into actual projects. The range of tutorials covers a variety of scenarios, ensuring there’s material for both beginners and more experienced developers. In addition, they written by people across the organisation, not just by a single team responsible for documentation. Contributions come from product teams, solution engineers, community leads and others who have different responsibilities. This diversity of input means the tutorials address practical challenges and remain closely tied to real developer needs.


https://www.storyblok.com/tutorials




Confidence Through API Docs

API documentation is often where developers spend the most time once they move past the basics. Storyblok’s API docs are effective because they are both complete and easy to navigate. The documentation is clearly divided into areas like the Content Delivery API, Management API, GraphQL API, and Image Service. Each section has consistent structures and examples, so developers know what to expect. The inline examples make a big difference. Instead of piecing information together, you can see exactly how a request or response should look. This makes it easier to test ideas quickly and reduces the guesswork that comes with less structured documentation.

https://www.storyblok.com/docs/concepts/

Where poor docs can make you want to walk away from a product, Storyblok’s guides did the reverse — they made me want to stay, build, and see what else the platform could do. If you're at all curious about the headless CMS that is Storyblok, give the start up guides a go. It's not going to take you long.