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