Experimental documentation site

#1

Hello all,

For about a year now we have been experimenting with using this forum as a mechanism to maintain the documentation for the project. This has been working quite well in several fronts:

  • Increased visibility for the content
  • Content trivially editable by everyone
  • Forum’s spam control helps preventing abuse
  • Searches hit the documentation too
  • Documentation can be easily discussed
  • Nice change tracking

That said, there are some downsides too:

  • Lack of a consolidated picture
  • Documentation topics get lost amid discussions
  • Too much noise due to forum features

Well, not anymore! Here is a new experimental site that attempts to fix those downsides:

This is on a temporary domain for now, and still lacks content compared to the official site. But with a little more work we can probably turn this into our official reference.

Some details:

  • Site is entirely based on forum content.
  • Content is cached for an hour before being refreshed.
  • There’s no topic registration. They just work as long as it’s in the #doc category.
  • The initial page and outline both come from the outline topic.
  • Below every page there’s a link back to the respective forum topic.
  • It’s supposed to work very well on phones.

Please let me know how it goes.

Core dump when built on incorrect libraries
Behaviour for installing classic, devmode and unsigned snaps in a GUI
Improving the documentation
Create Security documentation
#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).
#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.

Improving the documentation
#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”.

#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.

#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.

#10

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

#11

Searching is now supported!

#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?
#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.

#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. Environmental variables of Snapcraft (SNAPCRAFT_*) should be documented, 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?

#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