Snap documentation in 17.04?

Bug #1658785 reported by Chris Perry
8
This bug affects 1 person
Affects Status Importance Assigned to Milestone
ubuntu-docs (Ubuntu)
Fix Released
Medium
Chris Perry

Bug Description

Do we say anything about snaps in the 17.04 desktop help and if so what do we say? If snaps are experimental and subject to change then perhaps we should say nothing? Below I give some points about snaps worth thinking about (as regards how we document them):

The logon to Ubuntu One in Ubuntu Software when one tries to install a snap will surely create confusion. I saw one example on the #ubuntu channel where people were confused by it (with good reason in my opinion). At present you don't have to logon to Ubuntu One if you install a snap from the command line. Why are Ubuntu Software and the command line treated differently in this respect?

I don't know much about snaps but in the manual for the snap command there are options to buy a snap and log on to the snap store. I would imagine that at present there are no snaps that one has to pay for - but there will be soon?

Snaps are visible in the Disks application as "devices". This is very confusing in my opinion.

Related branches

Revision history for this message
Gunnar Hjalmarsson (gunnarhj) wrote :

I know very little about snaps, but basically it's just a package format, and not a proper topic for the desktop user guide. (We don't talk about the Debian package format in the guide either.)

With that said, yes, there is an inconsistency as regards Ubuntu Software vs. terminal, but OTOH we do (almost) not mention the terminal way anyway.

As regards shown in Disks, according to bug #1637984 it will be changed.

Revision history for this message
Chris Perry (clissold345) wrote :

Hi Gunnar, thanks for your reply. We don't need to decide what (if anything) to do until shortly before Documentation String Freeze (March 16th 2017). I suggest we stick to general principles (as regards maintaining the documentation). Eg if one of our procedures has changed we normally correct the page and if we see something that we think will cause a good deal of confusion for users we normally document it. Of course the meaning of "a good deal of confusion" is subjective.

Thanks for the link to bug #1637984. It's not assigned to anyone, so presumably it won't be fixed any time soon? I see that, due to the Disks application listing snaps, disk-partitions.html is no longer entirely correct. It says "... In the left pane, you will find a list of hard disks, CD/DVD drives, and other physical devices."

Revision history for this message
Peter Matulis (petermatulis) wrote :

For now, snap documentation is found here:

http://snapcraft.io/docs

Revision history for this message
Chris Perry (clissold345) wrote :

Another point that may be relevant to this bug is that some applications (eg vlc, hexchat) are listed twice in Ubuntu Software (I'm running 16.04 amd64). This will surely confuse users. Even if the user knows that one is the snap and the other is the non snap it's not immediately obvious which is which. (Snaps seem to be much bigger than non snaps, so the bigger package (of two) will be the snap.)

Revision history for this message
Gunnar Hjalmarsson (gunnarhj) wrote :

I agree that there are pending snap related questions, but please note:

1. Snap related things are in a preliminary state, and changes happen continuously.

2. We are not enough informed to distinguish between bugs and intended behavior.

I don't think we should add things to the docs only based on what we stumble upon, because if we would do that, there is a great chance that we document buggy behavior, and we don't want to do that. The docs which Peter pointed at target the developers, and I don't think they give any guidance with respect to the issues mentioned above.

I think we need expert input as a base for considering if there is anything about snaps which would be suitable to mention in the desktop guide. So, Chris, if you want to ask some developer involved in the snap development about it, it's great. But in the lack of such input I think we should keep this bug open in this cycle.

Revision history for this message
Chris Perry (clissold345) wrote :

Hi Gunnar, thanks for your reply. Yes I'll try to get some designer/developer input on this subject.

Revision history for this message
Chris Perry (clissold345) wrote :

Hi Will, could you give the Docs Team some guidance about what to say about snaps in the the 17.04 desktop help? A user of the desktop help will typically install and remove packages using Ubuntu Software (not the command line). So as regards the desktop help I'm only concerned about how snaps affect the GUI. My main concern is to avoid confusing people who read the desktop help (which includes people who follow procedures in the desktop help). As I understand it the sources of possible confusion are:

1. Some packages are listed twice in Ubuntu Software (one is the snap and one is the deb package). In such a case how does the user know which to install? What do we say in the 17.04 desktop help?

2. When users try to install a snap via Ubuntu Software they get asked to log on to Ubuntu One. The 16.10 desktop help documents installing packages using Ubuntu Software but doesn't document log on to Ubuntu One. What do we say in the 17.04 desktop help?

3. The 16.10 desktop help mentions that the Disks application lists "hard disks, CD/DVD drives, and other physical devices", - I'm reading this as meaning everything listed is a physical device - which is not true any more since at present Disks lists snaps too. What do we say in the 17.04 desktop help?

Revision history for this message
Will Cooke (willcooke) wrote :

Hi Chris, thanks for picking this up.

1. At the moment there is no way to tell from the Software GUI app that an application is a snap or a deb. Snaps are prioritised, and so will appear at the top of the list when doing a search. But there is currently no way of telling the packaging format from the Software application. If an app is listed twice then there is a high chance that the top one will be the snap.

2. A U1 login is required to authenticate against the Snap store. It would be great if we could document the steps involved in logging on to the store via Software. This should be straightforward. The prompts in Software are a simple web-view to the normal U1 sign-up/sign-in pages.

3. We're looking at a way to hide snaps from Disks as I think it is confusing. But right now, as you say, it shows them. If we can explain that Disks also shows "loop devices such as mounted ISO images or installed Snap applications" (maybe with an explanation of what a loop device is) and that these can be ignored - I think that will cover it for most users.

Revision history for this message
Chris Perry (clissold345) wrote :

Hi Will, thanks for your reply. So you think it's fine to document points 1, 2, and 3 above in the 17.04 desktop help? The reason I'm asking is that once Ubuntu 17.04 is released the 17.04 desktop help is basically available, without corrections, to the world for the (short) life of Ubuntu 17.04. So we don't want to document things that may be changed soon after they're documented.

I think documenting points 1, 2, and 3 briefly should be straightforward.

Revision history for this message
Will Cooke (willcooke) wrote :

I'm +1 on documenting them. It will help to reduce confusion.

Revision history for this message
Chris Perry (clissold345) wrote :

Hi Will, thanks. I'll discuss some details of the changes, and when to do them, with Gunnar.

Revision history for this message
Chris Perry (clissold345) wrote :

Hi Gunnar, I'm proposing to make minor changes to the following pages:

addremove-install.html
addremove-remove.html
disk-partitions.html

As regards installing and removing applications I'm proposing to say that there are two package formats: Debian packages and snap packages. In order to install or remove an application available as a snap package the user has to log on to Ubuntu One. Snap packages have advantages over Debian packages (I'm not planning to say what they are) so it's recommended that where there's a choice of format the user installs the snap package, which should be the first of the two applications listed.

The change to disk-partitions.html will be three or four words only. I'm not planning to say what loop devices are. It's not relevant to that page.

What do you think of this proposal?

Revision history for this message
Gunnar Hjalmarsson (gunnarhj) wrote :

I wouldn't say anything about advantages/recommend as regards snaps. For instance, as regards VLC I have observed two significant bugs with the snap: 1. Translations don't work, and 2. Capturing a stream to a file doesn't work either.

<rant>
To be honest it makes little sense to me to show both alternatives in Ubuntu Software. And prioritizing buggy snaps isn't exactly user friendly.
</rant>

Besides that I agree on your approach.

Revision history for this message
Chris Perry (clissold345) wrote :

Hi Gunnar, thanks for your reply. Yes that's fine. For 17.04 I'll drop the bit about snap packages having advantages over Debian packages and I'll drop the bit about recommending the snap package (in the case that both formats are available). But I'll keep the bit that mentions that some applications are available in both formats.

The changes are minor. I should have time to do them in the next day or two.

Changed in ubuntu-docs (Ubuntu):
assignee: nobody → Chris Perry (clissold345)
importance: Undecided → Medium
status: New → In Progress
Revision history for this message
Gunnar Hjalmarsson (gunnarhj) wrote :

On 2017-02-09 21:11, Chris Perry wrote:
> But I'll keep the bit that mentions that some applications are
> available in both formats.

+1

Changed in ubuntu-docs (Ubuntu):
status: In Progress → Fix Committed
Revision history for this message
Launchpad Janitor (janitor) wrote :

This bug was fixed in the package ubuntu-docs - 17.04.1

---------------
ubuntu-docs (17.04.1) zesty; urgency=medium

  * scripts/validate.sh:
    - Modified so it can be called via a symlink from 'ubuntu-help/C'
      or 'html'.
  * power-hibernate.page:
    - Changed command due to upstart->systemd transition.
  * Bump version to 17.04 / zesty.
  * html/ubuntu.xsl:
    - Make unordered lists bulleted and not numbered (LP: #1649554).
  * keyboard-layouts.page:
    - Note about how to show rarely used xkb layout variants.
  * Updated ubuntu-help.pot.
  * debian/compat, debian/control:
    - Bump to debhelper version 9

  [ Chris Perry ]
  * tips-specialchars.page:
    - Section "Compose key" updated (LP: #1624778).
  * addremove-ppa.page:
    - Revise PPA description (LP: #1628706).
  * keyboard-layouts.page:
    - Move text of marginal note.
  * mouse-middleclick.page, mouse-touchpad-click.page:
    - Revise description of middle-click from touchpad (LP: #1617718).
  * power-lowpower.page:
    - Update since related control in "System Settings -> Power" has
      been removed (LP: #1599264, LP: #1641786).
  * accounts-add.page, net-firewall-on-off.page:
    - Minor clarifications.
  * net-wireless-*.page, net-problem.page:
    - GUI conformity modifications (LP: #1637126)
    - New shared section (LP: #977251)
  * addremove-install.page, addremove-remove.page:
    - Clearer description of Ubuntu Software's focus on applications
      (LP: #1637861).
    - Mentioning of snaps (LP: #1658785).
  * printing-setup.page:
    - Section about network printer added (LP: #1630272).
  * mouse-mousekeys.page:
    - Improved description of mouse keys (LP: #964727).
  * disk-*.page:
    - GUI conformity modifications (LP: #1651360).
  * List type explicitly stated on multiple pages.
  * addremove-creator.page:
    - New page describing Startup Disk Creator (LP: #1569532).
  * security-settings.page:
    - New page describing the Security & Privacy panel in System
      Settings (LP: #1200381).

  [ Doug Smythies ]
  * scripts/validate.sh:
    - Changed to --strict validation.
  * ubuntu-help/C/legal.xml:
    - Specify https to avoid a "permanently moved" redirection.

 -- Gunnar Hjalmarsson <email address hidden> Mon, 20 Feb 2017 15:11:00 +0100

Changed in ubuntu-docs (Ubuntu):
status: Fix Committed → Fix Released
To post a comment you must log in.
This report contains Public information  
Everyone can see this information.

Other bug subscribers

Remote bug watches

Bug watches keep track of this bug in other bug trackers.