Thanks for working on this, and for highlighting desktop toolkit documentation. You’ve raised a really important point, and one we’ve spent considerable time discussing internally. It’s definitely something we want to get right.
Part of the delay in writing a good set of docs for this has been waiting for desktop extensions to mature enough to handle the hard dependency parts - these extensions should transform the process, and they’re close being ready.
Another part has been that we wanted to make sure there was a wider doc support structure for snap building before tackling desktop integration. This is what we’ve been working on with the Snapcraft build, debug and publishing docs roadmap, and it’s almost complete too.
I think we can do this in both of the ways you suggest. A walkthrough is really useful, and helps give a wider context to how snaps are built, even when they don’t fit your exact use-case. It’s also great for Google, etc. Adding a new table to Creating a snap to link to these makes good sense to me.
But as you also mention, a walkthrough doesn’t fit into our current (published) docs style. I think to integrate both, we need to make sure the core details for what’s discussed in any walkthrough are included in the more formal doc structure. I think walkthroughs should be a little like CI testing in code - they bring together the various elements of what’s already documented into a fully working example, but they shouldn’t be adding new ‘functionality’ themselves.
Adding to the wider docs is something I (or anyone, really!) can do if you feel like we’re not explaining something clearly, or if you feel a topic has become vague or outgrown its original intent. And it’s easier to do when that content already exists, whatever form it takes.
TLDR:
- thanks!
- I think walkthrough-style docs for desktop toolkit integration is a good idea
- desktop toolkit integration is currently changing, but still worth documenting
- a new table on Creating a snap is a good place for them
- I/we need to make sure whatever we cover in a walkthrough is easily discoverable and more formally documented in the normal doc structure. This may be easier to do after a walkthrough has been written.
I’ll also have a discussion with the Snapcraft/Advocacy teams on how best we can handle desktop toolkit integration.