Snap documentation

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.

Can we please use the shorter version?

Okay, so which do you prefer?

ID Path
6799 /creating-a-snap

Or:

ID Path
6799 /creating-a-snap

Or:

Topic Path
Creating a snap /creating-a-snap

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.

2 Likes

All the content of Building the snap on Docker has been merged into Build on Docker a while ago.

The first page however, still shows up in google searches:

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?

That’s a good point, thanks - and thanks for the edits. I’ll add the redirect now.

1 Like

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.

@degville, what do you think?

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.

I have some stuff I need your help with. I’m not completely done cleaning up these pages, but having them online would make my job a bit easier.

Please give the following pages a canonical url.

Feel free to change the path etc.

Topic Path
Adding OpenGL/GPU support to a snap /docs/gpu-support
Desktop files for menu integration /docs/desktop-menu-icon-support
Desktop applications /docs/desktop-applications
GTK3 applications /docs/gtk3-applications
Snapcraft Extensions /docs/snapcraft-extensions
The gnome-3-28 extension /docs/gnome-3-28-extension
The audio-playback interface /docs/audio-playback-interface
The audio-record interface /docs/audio-record-interface

Pages to turn into a wiki

I made them or I want to edit them.

Pages to add to the sidebar

I propose to add this to the sidebar. I’ll also link to the specific tutorials (GTK3, qt5, …) from the “creating a snap” page.

Pages to redirect

redirect https://snapcraft.io/docs/snapcraft-lifecycle to https://snapcraft.io/docs/parts-lifecycle

1 Like

I’ll make all the necessary fixes you’ve requested - thank you for all this!

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.

1 Like

Thank you, @degville. Good reasoning about not making it a wiki, thanks for elaborating

1 Like

Can you change the ToC link “Extend the build” to more closely match the name of the page it links to, “Iterating over a build”?

1 Like

I just created a reference page for the craftctl tool. I think it would fit nicely in the ToC under “Snapcraft”.

It’s there now - thank you!

1 Like

Hi! There’s a typo after the first sentence:

dependency-free. s

Awesome, thanks for letting me know. Looks like an editor command :slight_smile: Now removed.

Can we add the Using the REST API | Snapcraft documentation article before the Managing snaps > snapd REST API node? That is quite a useful introductory post on using the snapd REST APIs.

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.

1 Like