I get it. My point is a more conceptual one, to be raised upstream: if we are not doing anything other than taking Graham’s suggestion of title in 99.9% of the cases, then the whole exercise seems kind of pointless. We don’t need so many people in the loop.
Can we please use the shorter version? The second part is not really a link, but rather the suffix that generates the link. So if the link doesn’t work, it’s the underlying mechanism that is broken and not the link itself. Also, the link won’t work as soon as the file is put live either, as there will necessarily be at least a short delay between it being saved and the system acting on it. So the shorter form is both more pleasant to read, and more appropriate it seems.
The last one feels like a pretty good trade off between ease of writing it the first time, ease of reading, and convenience in terms of clicking on the link to see the content.
So I removed the content of the first page and added a notice redirecting to the correct one. Is it possible to remove the page entirely and create a redirect pointing /docs/build-snaps-on-docker to /docs/build-on-docker?
I’ve been gathering and updating documentation for creating snaps of desktop applications. This is tricky to get right and very specific to which toolkit you use.
Given the many questions on this forum about desktop toolkits, it’s clear that many people are struggling with this, so we should give it a clear place in the docs, but I’m not sure where.
The easiest route might be to just add Desktop applications to the navigation, but it doesn’t really fit in there. I added a link to this document in the checklist page, but I don’t think that is visible enough.
Creating a snap has the “common languages and platforms” table. I was thinking of adding another table or column called “Desktop toolkits” which contains “Electron” (moved from “languages”), “Qt”, “GTK”, “Java Swing”, “wxWidgets” and “other”. This could be expanded in the future with other toolkits and things like OpenGL (which is more complex than simply adding an interface) and ffmpeg.
However, many of these topics don’t really fit into the style of a complete walkthrough. I can update them a bit to look more similar, but I’m not sure if it makes sense to turn pages like Qt5 and GTK into complete walkthroughs since these are meant to be used together with one of the languages. For example, an application might use Python + GTK3 or Go + Qt5 etc.
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
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.
Can we pin this so that it appears at the top of the doc page for easy discovery of the “entry point” so we can find the links that are on the sidebar easily? Also, should this be a wiki?
I’ve just pinned the topic, thanks for the suggestion.
This is the only page that isn’t a wiki because we need some gateway control over the docs publishing. A small error in the table can completely break the final output, for instance. It also contains re-directs for old pages, which could also break the docs rendering and other pages too.
Hello! Thanks for your suggestion - it makes a lot of sense. It’s not quite a Reference document, but it mostly is. Ideally, it should probably be split into a broader how-to guide.
I do have a short-term goal to expose much more of our documentation through the navigation.