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