Experimental documentation site

doc
2
3

Feedback after playing around with this:

  • This is a massive improvement on reading this documentation from the forum directly.
  • The links to the forum topics were easy to find and use, which made it easy to work out how to edit it.
  • The documentation feels fresher than docs.snapcraft.io.
  • I wonder if it will be a bit “techy”. We’ll have to be careful to have some higher-level docs that are easier to read (perhaps more like docs.snapcraft.io curently).
1 Like
4

I tried to migrate https://github.com/snapcore/snapd/wiki/REST-API to the forum but the content is too big (>32000 characters) to fit - any ideas on how manage this? Obviously splitting the page would work but I’m wondering how this would look.

5

Thanks for the feedback, and glad you’re enjoying it.

It does feel a bit like that right now, but that’s because much of what is there was the documentation inherited from our ancient wiki, which was itself extracted form the development tree before that.

The goal is to work towards it covering a wider spectrum, though, and the priority is definitely on the using and publishing side of things.

I’m able to easily increase the maximum post length up to 100kb, but I’m not entirely sure this is a good idea, and it’s also part of the reason why I hadn’t migrated that page yet. It feels too long, both to read and to write, and its formatting also doesn’t feel fantastic.

How about splitting it up in a few pages which are scoped after the subject being covered? It doesn’t have to match 1-to-1 with the URLs. Something vaguely along these lines:

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

This also means we can more easily fix the styling to be pleasant, by doing one page at a time instead of trying to do it all. Conversations around these also become better scoped and more sensible.

6

Actually, let’s take the chance to fix a small misconception: the API in the daemon is not REST at all. We can just call it “Daemon API”.

1 Like
7

In the long-term, is docs.snapcraft.io going to be abandoned in favour of the unified site?

8

It depends on how well this works out. That’s why it’s experimental. But if we make this documentation be comprehensive, pleasant to consume, and remain up-to-date, yes that’s what I would like to do.

So far it’s looking good.

2 Likes
9

The big gap I currently see in docs.snapcraft.io is a lack of search, which is also missing in the experimental site.

Presumably the expectation is that search engines index the site, and we rely on e.g. DuckDuckGo to find topics? In-site search, as can be found in many documentation sites is a nicer experience.

2 Likes
10

That’s a good point. Let me see if I can get something nice in place with a quick spike.

1 Like
11

Searching is now supported!

2 Likes
12

Looking good! I’m glad the docs issue is being worked on! Some thoughts:

  • Is the source of this site online somewhere?
  • Maybe it’s best to create a bot that automatically turns any post in the #doc category into a wiki post?
1 Like
13

@galgalesh Thanks!

The source of the documentation is right here in the forum, but you mean the source that runs it, not the documentation right? It’s not yet public, but it will be somewhere in https://github.com/snapcore soon.

As for making posts as wikis, we can setup the forum to do that by default without a bot, but I don’t think we want that. If you navigate through #doc, you’ll see that many posts there wouldn’t be proper as a wiki. That said, we do want all actual documents to be wikis, so if you see one that is not please comment on it.

14

Added the new logo to the experimental documentation site as well.

1 Like
15

3 posts were merged into an existing topic: Snapd problems

16

A significant problem with using the forum to post documentation is navigation.

If you find an article there is no way to get back to the ‘index’.

Having the index as a stand alone page is also somewhat frustrating is navigating between pages in the doco becomes slow (select an article, read the article, click back to get to the index, select the next article).

A better method of navigating the doco would be highly desirable.

17

It’s also not clear to me how a document gets promoted from “post” to “documentation”. Does it just magically appear on @neimeyer’s site by being tagged as “doc” or do we have to request it be blessed somehow?

18

Oh, and I can’t figure out how to make a post turn into a “wiki” either.

19

And… In the first post above it is stated that:

Searching for a post on the doc site proves that not everything in the “doc” category is copied across, e.g. [MOVED] Environmental Variables that Snapcraft Exposes, so what mechanism is the doc site using to differentiate between docs that are displayed on the site and not-docs that are prohibited from appearing on the doc site?

1 Like
20

As I understand it, the mechanism is just to use the outline topic as the ‘home page’, and docs that are linked from there will appear.

Note that the example you give is on the site, just not linked anywhere. With URL hackery one can get to https://snapdocs.labix.org/look-at-this/5368

21

My suggestion to mitigate the recent misinformation about snap security: