Hello Emanuel and thanks a lot for your detailed response!
While I’m sure Jason will have a few notes to add on his own, I (as a fellow plugin developer and a member of this community) also want to add some to the discussion.
There’s this core issue where people do not employ our guidelines on Plugins API usage, our documentation exists, but people don’t want to follow it.
[…]
People use private APIs, instead of the official ones […]
Maybe I’m reading this wrong, but it looks like Sketch has no idea why plugin developers often have to fall back to the native APIs and thus ignore the official JS API (and by extend the official documentation) and what could’ve been done to convert them?
If that’s so, I’m happy to revive my old post from “Sketch Friends” Slack circa 2021 which, I hope, will reveal at least some of the reasons:
👉 Click to show the post 👈
Re: https://sketchplugins.com/d/2419-why-are-sketchs-plugin-api-docs-so-incomplete – this post is also worth a read.
[…]
1. Why use this?
[…]
One major upside of using the official API package could be that it’s always up-to-date with the Sketch internals, but that’s not always true unfortunately – even with public updates – so we still have to test and tune things ourselves.
2. No clear API boundaries.
It’s not clear from the outside what exactly should be included into the JS API and what shouldn’t. Are some features not covered yet because nobody asked for them? Or are they not included into the JS API because the underlying Sketch feature is subject to a major update or even removal soon? We don’t know. There’s quite a lot of feature requests open in sketch-hq/SketchAPI, some of them been open for years without an answer.
Or maybe third-party developers should just use sketch-hq/SketchAPI as a “core” package and fix bugs/build their own APIs on top of that instead? Well, this brings us back to my previous point #1.
3. Maintenance and decision making.
Sketch JS API is not a regular open-source project because it relies on private Sketch implementation details knowledge not available to third-parties. This makes Sketch the sole owner and maintainer of the project, but the rules of decision making are not clear enough for a public project:
- How it is decided that a PR with a particular API update is worth merging into the official repository?
- Can the Sketch team provide feedback and suggestions on the internal API usage that we (third-party contributors) often have to “guess” based on Sketch.app disassembly and header dumps?
- If it doesn’t, who decides how a particular JS API feature should be implemented internally with native API? Are third-party developers even expected to use it in their PRs at all?
Now, it’s been a couple years and none of these core questions about the official JS API have been answered and no changes have been made to address any of them.
Not sure how you can build trust in the official API if there’s virtually no communication (except for Ale and Kevin posting occasional notes in the private Slack channel) and no clear guidance from the team. Basically, developers were/are still on their own even if they choose to rely on the (not that reliable – sorry, no offense!) official API.
Doing that, together with just fewer people being interested in writing plugins in the first place, its for all those reason we have chosen to invest our time elsewhere as of late.
That sounds like a proper reasoning and a perfectly valid one. Admitting that third-party developments are no longer a focus for the team is absolutely fine and I’m sure the community would understand that decision for their beloved design tool to become better in the long run. We just wanted a bit more clarity and transparency on the topic from day one.
But ghosting third-party developers and now blaming them (at least partially) on the current state of things in the ecosystem (which, to be honest, has been like this since forever)?
I admire Sketch as a product and a company (I even was on track to join the team one time – and I’d still join now if I had a chance). And I definitely don’t want to play the blame game and upset anyone involved.
Nor do I believe that any amount of sad posting will change the situation – at the end of the day it’s all up to Sketch and the only thing we as a community can do is to accept the new reality and to adapt (or not, and thus go gentle). This is still a sad post, but I couldn’t help myself, sorry.