canonical/open-documentation-academy

Snap: improve interface management documentation

Open

#8 opened on Jan 25, 2024

View on GitHub
 (9 comments) (0 reactions) (1 assignee)Python (99 forks)auto 404
diátaxisexplanationhelp wantedhow-tosize 2update

Repository metrics

Stars
 (119 stars)
PR merge metrics
 (PR metrics pending)

Description

The current interface management documentation isn't as a how-to, and isn't clean, clear, or as simple as it could be.

This task is to improve this documentation to make it easier to understand, to make it task-oriented and to either remove any superfluous details, or move them to the explanation section:

How-to: https://snapcraft.io/docs/interface-management

Explanation: https://snapcraft.io/docs/interfaces

Background

Snaps use plugs and slots to allow access to system resources, but the terminology isn't easy to understand for a general desktop audience. This problem is repeated throughout the snap-related documentation.

Prerequisites

You will need some experience using snaps and working with connections and interfaces.

See also Contribute to our documentation.

Contributor guide

Research direction
Start by reading the linked interface management documentation and the 'Contribute to our documentation' guide. Then outline the current structure, identify non task oriented sections, and rewrite the interface management page as a clear how to, moving superfluous details to the explanation page.
Tech stack
None
Domain
documentation
Issue type
Documentation
DifficultyEstimated implementation difficulty for a new contributor, from 1 for very small changes to 5 for expert-level work.
2
Estimated timeA rough time range for an experienced contributor to investigate, implement, test, and prepare a pull request.
Half day
Activity statusHow available the issue appears right now: fresh, active, stale, blocked, or waiting on maintainer input.
Active
ClarityHow clearly the issue explains the expected change, acceptance criteria, and next step.
Clear
Prerequisites
Experience with snaps
Newbie friendlinessA 1-100 score estimating how approachable this issue is for first-time contributors.
70