This is a list of the documentation issues and documents that we (the snap team) are currently working to improve. It isn’t necessarily a list of documents we want to write, but it is a list of subjects we know need attention or need clearer and more concise documentation.
Our documentation is a community effort, published via this forum. We warmly welcome community contributions, suggestions, fixes and constructive criticism. See Contribute to our documentation for further details.
Snapcraft
General items
Restructure Snapcraft docs navigation to use Diátaxis
Create a strategy to audit Snapcraft docs; updating and editing for consistency with Diátaxis- Pull in and update out-dated tutorials from
/tutorials - Edit and revise platform Quickstart guides
- Snap key signing
- User details/SSSD support from snaps
- document defaulting to $HOME
- Scriptlets
- Tackle the snap.yaml and snapcraft.yaml ambiguity
- Document GitHub actions for building
- Add a simple packaging bash script example
- Add a Python/GTK application example
- Use of bind or symlinks in Layout
- Troubleshooting
- Using
snappy-debug.security - Using debug strace
snapd
general
- Restructure Snap docs navigation to use Diátaxis
- Create a strategy to audit Snap docs; updating and editing for consistency with Diátaxis
- port, refactor and split API REST docs (and link back)
- Using in-development features
- Bash completion
- $HOME/snap is the writable area for snaps
- Document preseeding (won’t work with LXD)
- Differentiate system options for Ubuntu Core
- Document hook execution ordering
- Improve dbus interface documentation
upcoming this cycle
- Update: Quota docs to include service sub-groups
- snapctl model (in 2.57)
Bugs
General documentation targets
- Enable and migrate to foldable navigation
- Convert Snap docs to use the Diátaxis framework
- Convert Snapcraft docs to use the Diátaxis framework
- Split interface docs into user and developer sections
- Investigate automatic backup/snapshot of docs to a git repository
Style and consistency reviews
- Using Tracks
- Architectures
- Make better use of, and update, Documentation Drive Hit List
Proposed
- Remove dollar signs at the beginning of the shell prompts (to be consistent with other Canonical docs and the Ubuntu wiki)
Archived
Completed documentation tasks
Snapcraft
General items
- Overview
- Installation (in a central place)
- Bases
- Document filesets
- Working with Multipass (Snapcraft v3)
- Debugging builds:
snapcraft --debug - Publishing
- deprecate cleanbuild. See also SNAPCRAFT_BUILD_ENVIRONMENT.
- Re-work LXD advantages alongside Multipass (Snapcraft v3)
- macOS brew snapcraft and multipass overview
- Update snapcraft.yaml to new format with fixes
- Replace snap with snapd version references in interface docs
- Edit and add to outline Extracting information from sources in snapcraft parts
- update non-table formatting of snapcraft.yaml reference pages
- sorted snapcraft.yaml reference pages into alphabetical order
- incorporate Snapcraft 3.x release notes into docs
- update Layers doc to make its use-case/examples clear
- add missing adopt-info and related keys to references
- Environment variables (snapcraft)
- Environment variables (snapd, with wider explanation)
- Need documentation on assumes (Better guidance for missing "assumes" features)
- Command syntax (esp. snapcraft clean)
- Broaden parts documentation
- update Debugging Building Snaps for Snapcraft 3 (there is no
prime/) - Glam up your Store page (see Publishing missing)
- Store metrics and reviewing progress
- Adding and working with interfaces
- Tracking down dependencies
- Update snapcraft walkthroughs to use bases
- Migrating from remote parts/pre-base snapcraft.yaml
- Re-work Docker to emphasise its use with snap CI (Snapcraft v3)
- Using plugins
- Debugging builds:
snapcraft --shell - Using
snapctl
snapd
general
- Confinement
- snap.yaml is incomplete
- Base snaps [targetting Ubuntu IoT Dev docs]
- Improvements in the content interface
upcoming this cycle
- snapd: Health checks
- snapd: Hotplug user documentation
- snapd: Hotplug developer documentation
- snapd: Snapshot documentation
- snapd: Epoch documentation
- snapd: Changes to interfaces output (update all references)
- snapd: Connections
General
- Add docs search to snapcraft.io/docs
- snapcraft.io/docs landing page
- Replace boiler-plate intro
- Create a simple matrix of doc locations to visit
- Improve contribution guidelines
Style and consistency reviews
Bugs
- Search for
snapcraft_arch_triplethas no results (should be Environment variables that Snapcraft exposes). - [Test it](https://www.ubuntu.com/search?siteSearch=snapcraft.io/docs &q=snapcraft_arch_triplet).
- missing Xubuntu, Kubuntu and Lubuntu snap install docs (plus mention generic flavours)
