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.
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.
+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!
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
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.
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.
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.
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.
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.
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.
