I think that examples are underestimated as developer experience tools. There are definitely stages of developer engagement, and examples are a sweet spot. You have someone actively engaged (enough to want to try code) but new enough that they may not be clear where to start.
GitHub makes it so easy to set up examples and let folks clone them. It can also be a discovery mechanism.
Just make sure the examples continue to work, are audited periodically and have good readmes.
Something I wish SaaS and platform vendors took a little more care over though is being aware of the difference between thinking of usecases ‘developer-first’ and ‘DevRel-first’
> ... testing our demo is just one single standard command (docker-compose up), that integrating it is a matter of minutes (less than 30 lines of code, ready to be copied from our examples)...
Great, your sample scenario, neatly sandboxes with all its dependencies and only its dependencies can be brought up in a single line of live-coding to wow the crowd.
But how do I integrate it into my existing codebase? How does it interact with my integration tests? Having got it running on my machine, how do I get it working in production?
Are you actually focused on making it easy for developers to use in the context they’ll actually have to use it, or focused on making it look easy to use in a cherry-picked simplistic scenario?
That's a set of great points. Thanks for suggesting :-).
We are getting started, so we have a limited bandwidth. However, we are thinking to developers and to how they will have to integrate. So fare we tried to keep that as simple as possible given the limited time we have. We created a couple of sample examples with two popular stacks and we are adding others in the next days (basically it's the most basic project you can create with such framework with the integration; the idea is that if you are familiar with the framework it should be easy how to integrate (plus the integration code is well commented and isolated, take a look https://github.com/saasform/saasform/blob/main/src/demo-expr...).
For the moment we kept the code as simple as possible, even if we know there is room for improvement. Also, we are almost always online on the discord server and we have weekly office hours in EU and US timezones)
Of course we don't yet have a stable solution for every thing, butwhat I wanted to highlight is that developer-first is one of our leading principles, even if it slows down a little the release pace.
I agree but with one caveat: If the difficult to integrate tool/library is open source, then one probably shouldn't ask likely already overworked maintainers for even more work. In those cases, one should probably be the change one wants to see by contributing the features, refactoring or documentation needed to ease integration.
1, Unfortunately not in all companies, Product Managers are engineers. So developer-first mindset is difficult to explain/educate. Their priorities are different.
2. I agree with this philosophy, but most of the enterprises run old monoliths which are built to solve a business problem without principles to guide them.
Author here: I think it also depends on the type of product. Sometimes it's better to release features faster than having a great experience.
Ideally using the product should be as straightforward as possible, so that it easy by design. However sometime the product feels just like a stratification of incoherent decisions one on top of another. And it's so painful to use.
GitHub makes it so easy to set up examples and let folks clone them. It can also be a discovery mechanism.
Just make sure the examples continue to work, are audited periodically and have good readmes.