Proposed new documentation outline


#1

This is a proposed alternative documentation structure.

The current documentation structure, as published at https://docs.snapcraft.io/, can be found on the Snap Documentation topic.

The below structure is an experimental work in progress and likely to change.

We’d appreciate feedback and suggestions.

Most of this documentation can be collaboratively discussed and changed in the respective topic in the forum. See the documentation guidelines if you’d like to contribute.

Content

Using snaps

Publishing snaps

Contributing

  • Snapd
    • Roadmap
    • API
      • Daemon API (versioning details, authentication, and index for subpages)
      • Snaps (snaps, find, aliases)
      • Configuration (not there?)
      • Aliases (aliases)
      • Interfaces (interfaces, connections (missing))
      • Assertions (assertions)
      • Changes (changes)
      • Services (logs, start/stop/etc (missing))
      • Miscellaneous (sections, users, create-user, icons, system-info, snapctl)
  • Snapcraft
  • Documentation guidelines
    • Style guide

Reference

  • Snapcraft syntax
  • Plugin options
    • Pre-built apps
    • Electron
    • Go
    • Java
    • Node
    • Python
    • Ruby
    • Rust
    • C/C++
    • MOOS
    • ROS
    • ROS2
  • Project plugins
  • Interfaces
  • Hooks
  • The snap format
  • Snap directory structure
  • snap command syntax and environment variables
  • snapcraft command syntax
  • Snap Store API
  • Deprecation notices

#2

Looks nice.
I’d also add the snapcraft deprecation notices under Reference


#3

I heard that active voice is preferred for technical documentation.


#4

I have an issue with

Can I run snaps?

because (today) nobody can “run a snap”. You can install a snap, and run apps from inside it.
It might seem like silly distinction, but before now people have been confused by having to install the snap.

Can we go with “can I use snaps” instead?


#5

+1 from me. I think you’re right about propagating confusion and we should be clear about what snaps are and what the do (and don’t do), especially with the first heading!


#6

+1 on “Can I use snaps” and “Deprecation notices”. I’ve made those changes to the wiki.


#7
  • On the Using snaps section, the first item: Can I use snaps? is the only one using a question mark, so maybe we can go for something more like Using snaps as other items of the section

  • +1 on the usage of Active voice


#8

I think we may need one more section between these two that covers scriptlets as an optional step:

“Extending the build”

Alternatively, we could home it under “Additional features” in the TOC and link off to it inside “Further customisations” in each Creating a snap guide. This is how the existing language guides work.

I’m not a big fan of putting things in front of all developers that will only apply to a fraction. It’s unnecessary cognitive load. But I can’t think of a better place for it that would still be discoverable by those who need it.


#9

Passive voice would be “A security model should be chosen”. The example you give is present continuous tense (“choosing”) vs. simple present tense (“choose”). Simple present tense is used in the imperative mood. That’s useful when giving a list of instructions (do this, then do that). Using continuous tense for all topics could make them look like sets of instructions when they aren’t.


#10

Forget my example, just read what I linked. Also:
https://developers.google.com/style/voice
or search for “active+passive+documentation”


#11

Could you please make sure you only use the path part of the URL for all links - in the form:

/t/snapcraft-yaml-reference/4276

Rather than:

https://forum.snapcraft.io/t/snapcraft-yaml-reference/4276

This is so the links will continue to work when this navigation is pulled into the documentation site.


#12

It appears that this outline isn’t actually be used in https://docs.snapcraft.io :-/


#13

Yes. None of the “Creating a snap” language pages are showing up in the outline, though other pages at the same level do show up. Is this deliberate?


#14

Yes. Currently, the plan is to keep the original outline, as published on the experimental docs site, and to keep to its principle of first and second level headings being concise pages leading to the other documents.


#15

Is the “Windows” part in the “creating a snap” section supposed to be a guide for how to snap a Windows application (using Wine presumably?)

I’m the author of this guide on how to snap a windows application in Wine. If you’re interested, I can rewrite the guide to look more like the other language pages so you can use it in the docs. What do you think?


#16

I think this is an example of a general problem with the docs navigation: we’re showing exactly the same level of outline detail, on the front page, as we are on every other page. This was easy to implement, but has awkward results.

It’s quite reasonable not to list the languages/frameworks/platforms in the outline on article pages. (And it reduces pollution of Web search results.) But it’s bizarre not to list them on the front page.

When I arrive at the front page, I’m looking for an answer. The most important thing, for the page to do, is to help me find the answer. Many things can help with this (such as a search function), but one ingredient is to show a lot of well-arranged links. Like Microsoft does and Apple does and Travis does. It reduces guesswork: for example, I shouldn’t need to guess whether you’ve put the Ruby information under “Getting started” or “Creating a snap” or “Developing” — all equally plausible.

For languages, frameworks, and OSes in particular, there’s also reassurance from seeing them name-checked on the front page, in the case where someone is encountering snaps for the first time. “Ah, yes, snaps do work with that thing I use.” (This is one of the reasons snapcraft.io now shows a grid of languages on the front page, too.)

The text “Welcome to the home of snap, snapd, and snapcraft documentation. Snaps are transforming the way we etc etc etc…” irritates me. It’s filler, conveying almost nothing tangible, when that space could have been used for so many more links to information.


#17

I think it’s better to show the complete index containing all pages in the sidebar, possibly with collapsed sections. I did not know the “creating a snap” sub pages like Python, electron, and such existed in the documentation, because they are never shown in the sidebar. I only found them by stumbling upon this very forum post. I never thought to look in the “creating a snap” page for more pages about specific languages. I just assumed that “creating a snap” contained generic information.

I cannot stress enough how important it is for visibility to include all pages in the outline. I just assumed the snapcraft documentation was incredibly limited. Even a Google search for “creating a python snap” doesn’t bring up those pages.


#18

Thanks for taking the trouble to let us know. This is valuable feedback, and we do regularly discuss the feedback we get. And I’m sure we will broaden the current outline as we re-organise and extend the documentation.


#19

Three months later, the deprecation notices exist on docs.snapcraft.io, but they are not linked to from anywhere (and their old URLs 404 rather than redirecting). Why? How can they be added to the published outline?


#20

I’ve just created a PR for this: https://github.com/canonical-websites/docs.snapcraft.io/pull/72