Reordering and cleaning the difference between doing and learning. #67
Conversation
|
Hi @PhilStollery. Thanks so much for this, and sorry for the delay responding. I'll take a look at your PR, but to answer your excellent questions first:
We don't have a standard because our standard approach is usually to try and avoid screenshots, for a few important reasons. They're difficult to maintain, and GUI elements often change, quickly making screenshots out of date. They're also difficult to find through a documentation search, especially if you're looking for a description. There are accessibility issues too, perhaps for people who can't use a normal display, and they're difficult to fit into translated documentation. This page is one of our few examples, though, because sometimes you do indeed need to show what you're writing about. What you've done looks good.
Good question! You can probably find examples of both in our docs, but we do have a strong preference for you.
No, but we absolutely should! This might actually be a great challenge for the Academy.
Thanks! You did the right thing. The reason for the HTML headers is to make-up for a limitation in Discourse documentation. |
|
Any update on my PR? |
|
|
||
| The creator of a snap selects the interfaces that a snap requires in order to function correctly. Common interfaces include those that provide access to the [network](/t/the-network-interface/7880), [desktop features](/t/the-desktop-interfaces/2042) and the [sound system](/t/the-pulseaudio-interface/7906). | ||
| The creator of a snap selects the category of interfaces that a snap requires in order to function correctly. Common categories include [network](/t/the-network-interface/7880), [desktop](/t/the-desktop-interfaces/2042) and the [sound system](/t/the-pulseaudio-interface/7906). <!-- TODO find out how to get the correct URL this link is out of date: should reference https://snapcraft.io/docs/audio-playback-interface> |
There was a problem hiding this comment.
While interfaces do belong to categories, I think it's more accurate to point out that the snap creator selects a specific interface rather than an interface category.
| is connected to a slot in another snap providing that resource. | ||
| A analogy to this is plugging an appliance into an electrical outlet that | ||
| provides the power it needs. | ||
| A connection between snaps is made when a plug from a snap needing a resource is connected to a slot in another snap providing that resource. An analogy to this is plugging an appliance into an electrical outlet that provides the power it needs. |
There was a problem hiding this comment.
This is good, thank you! Although not in the original text either, I think it may be worth pointing out that, most commonly, a connection is made between an application snap and the system snap, which permits access to system resource (the system snap isn't even listed, but can be seen as a colon : in the connections lists, eg. :x11.
|
|
||
| As with [classic confinement](/t/33649), a snap's publisher can request an *assertion* to automatically connect an otherwise non-auto-connecting interface. For example, the *guvcview* snap [requested](https://forum.snapcraft.io/t/auto-connect-request-for-the-guvcview-brlin-snap/6042) the camera interface be automatically-connected when the snap is installed. | ||
| As with [classic confinement](/t/33649), a snap's publisher can request an *assertion* to automatically connect an otherwise non-auto-connecting interface. For example, the *guvcview* snap [requests](https://forum.snapcraft.io/t/auto-connect-request-for-the-guvcview-brlin-snap/6042) the camera interface automatically-connect when the snap is installed. |
There was a problem hiding this comment.
I know this is in the original too, but it might be worth explaining an assertion. Or even remove the reference to assertions? It's quite a complicated subject for an introduction to interfaces, and may not be necessary for readers to understand. They may be better off just knowing that snap developers can also request that an interface is connected automatically.
|
|
||
|  | ||
|  |
There was a problem hiding this comment.
Thanks for improving the alt text!
|
|
||
| An interface is most commonly used to enable a snap to access sound playback or recording, your network, and your $HOME directory. But which interfaces a snap requires, and *provides*, is very much dependent on the type of snap and its own requirements. | ||
|
|
||
| See [Supported interfaces](/t/supported-interfaces/7744) for a comprehensive list of interfaces and what kind of access they permit. | ||
|
|
||
| <h2 id='heading--slots-plugs'>Plugs and slots</h2> | ||
| ## View all the snaps using an interface |
There was a problem hiding this comment.
This could be interpreted as _using an interface to view all the snaps _. Maybe some more like View the interfaces a snap is using ?
|
|
||
| You can see which snaps are using an interface with the `interface` command: | ||
| The `interface` command shows the snaps using an interface. For example, for the audio-playback interface you'd see: |
There was a problem hiding this comment.
I think there's a hint of ambiguity here in shows the snaps using an interface which is easier to understand with the which.
| The `interface` command shows the snaps using an interface. For example, for the audio-playback interface you'd see: | |
| The `interface` command shows which snaps are using an interface. For example, for the audio-playback interface you'd see: |
| ``` | ||
|
|
||
| In the above output, the [`camera`](/t/the-home-interface/7838) interface is not connected because its slot is empty. This means VLC cannot access any connected cameras. | ||
| In the previous <!-- above, left, right, below are assuming reading direction --> example, you <!-- TODO Style guide question, as authors should we talk directly to our readers YOU instead of WE --> can see that the `vlc:camera` interface is disconnected because it has an empty *Slot* entry. |
There was a problem hiding this comment.
Good question. There's no firm guide to this - both we and you are acceptable, but I prefer avoiding them when possible, eg. "In the previous example, the output shows that the vlc:camera..."
|
|
||
|  | ||
|
|
||
| Each interface can now be connected or disconnected by selecting the toggle switch to the right of its description, and you may be prompted for your password. |
There was a problem hiding this comment.
I really like moving this to the end, thank you!
Fixes #8
This is my first PR into the Open Documentation Academy. I've read the Canonical style guide but I still have some style questions:
My aim for this PR was removing doing content into the How To document. The explanation is now maybe a bit too simple? Should I expand on it?