Refresh Spin docs structure and key content

[itowlson]

The current Spin docs structure kind of dates from early days and a lot of our topics no longer fit comfortably within it. We have (or will have) at least three categories of documentation:

• How to
• Conceptual
• Reference

and goodness knows how many areas:

• Out of the box experience (intro / get started)
• Installation and upgrade
• Applications
• Triggers
• Services / Capabilities (this is things like outbound HTTP, Postgres/MySQL, key/value storage, etc.)
• Languages (a lot of the existing content might move to the multilingual tabs in the Triggers and Services sections but we want them to be in the TOC too)
• Templates
• Plugins
• Publishing / Distribution / Cloud (though maybe this is an Applications topic?)
• Extensibility / Authoring / Contributing (roughly, creating stuff for Spin as opposed to using Spin)

Of course these areas have overlaps e.g. "creating a new application" is an Applications topic but also relates to Templates, or "running a published application."

I would like to suggest (for discussion) a few things:

• Abolish the Advanced group. Some of those pages are triggers; some are extensibility/authoring/contributing; some are publishing/distribution.
• Organise the TOC into a larger number of more prominent groups, maybe via the topic areas described above, or maybe parking Reference topics into a separate group (or calling out tutorial / how-to topics).
• Tighten the TOC layout, or even accordion-style it, so readers can scan for more topics without scrolling.
• Refresh the quick start to be multi-lingual using the natty language tabs thing.
• ~Sort the language guides alphabetically, and add an entry for Brainf**k.~ Focus the language guides on what you need to know that are distinctive about that language (e.g. how to install nondefault parts of toolchain, where to install the templates from, what triggers/services are/aren't supported, favourite gotchas). The "how to write the HTTP entry point" could maybe be in the language tabs of the HTTP trigger topic. Or maybe this will end up being too much cross-referencing and we are better off duplicating that material under each language, but that really does mean we need more than one page per language.
• Crisp presentation of versions a la the version tabs in the registry page, or badges a la "Requires Spin 1.3." Or even archive the sites for old versions and have them available at dev.fermyon.com/spin/<version>/<page> with links to those sub-sites.

Apologies for the rambling - I am kind of thinking out loud and this is all very unformed - this is very much intended for discussion and to spark thoughts with those wiser than me, not as a prescription!

[itowlson]

We should also find a home for running Spin apps using Kubernetes or Docker + containerd-wasi-shim (if I'm right in thinking that works).

[karthik2804]

These are some exciting ideas. These are just some of my thoughts on it

• Every page with non-language-specific content should be updated to use multi-blocks.
• We can definitely tighten the ToC section using accordions.
• We should consider where examples such as persisting data using Redis/Postgres live. Should they move under spin and make the cloud section specific to cloud activities like managing the account, creating tokens, etc?
• Versioning is one other thing we need to think about. The badges idea sounds interesting.

[itowlson]

That's a great point about data storage @karthik2804. It's a topic that's big, important, and likely that people will scan for - although my engineer brain put it under "capabilities / services" it should totally be a top level thing in the TOC. In fact maybe most of those capabilities should be broken out into functional areas, e.g. networking, data storage, er, that's it (except for dynamic configuration which is a more inward looking app dev concern anyway).

Regarding Spin vs Cloud organisation - I would put "how to" and SDK references in the Spin section. They are part of Spin itself. Then in Cloud it would be appropriate to have "how this works in Fermyon Cloud" e.g. K/V consistency guarantees, secret management, etc. I'm reluctant to put things in Cloud just because they are available in Cloud, or we would duplicate 90% of the Spin docs!

One challenge will be how to approach non-Cloud deployment environments. It would be great if the Spin section included content on e.g. running Spin apps in Docker or Kubernetes. But at the same time, Fermyon can't provide authoritative info on how every feature works in every environment.

[karthik2804]

I love the idea of having different functional areas for "capabilities". I also agree that examples and the SDK reference (possibly the CLI) should be only in Spin and only things relating to specifically cloud should be in the cloud section.

On the final note of how to approach non-Cloud deployment environments, we could have a section that just hosts links to the actual docs elsewhere unless it is something we actively maintain. Developers will still be able to PR to update it.

[itowlson]

Well, I failed utterly at CSS so don't take this too seriously, but I roughed out what more topic-y TOC might look like and it came out a bit like this:

Too dense? Too many entries to scan? We'd want to reduce scrolling for sure, which might mean the sections had to be collapsible. And like I say this is very much for discussion.

(By the way, it is intentional that some entries occur twice, e.g. authoring templates under both Templates and Extensibility. The idea is to make it visible whether the reader is going "new template => 'new stuff' section" or "new template => 'template stuff' section".)

[karthik2804]

I love the way the menu is organized and I think we can make it collapsible but from a previous conversation I've had with Ronan, it might lead to discoverability issues of topics. But I do think with such specific topics, we can collapse the inner contents.

cc @flynnduism

[flynnduism]

That looks really well organized around clear themes for the user to find content under. Great undertaking @itowlson!

CSS Stuff

The current menu style is flat - no nested categories / sub pages, just sibbling pages and some 'labels' to group things. I think it's time to upgrade the menu style and function to better scale to the type of content structure we want long term, so happy to update the design in this regard.

Collapse/Expand Levels

A good rule of thumb for a menu like this is how much skimming / scrolling is needed to drill down towards the thing you want. There are 12 top level links, which is a good top level choice. Leaving all of the sections expanded like in the screenshot does make it hard to scan - so I would recommend the menu collapses child links (except for the active section) like in these example docs sites - Nomad, Helm, Stripe, etc

Things like arrows help denote the tree of contents.

[itowlson]

@flynnduism Your screenshot is exactly the sort of thing I was thinking about, but didn't know how to show - thank you! (And apologies for not roping you in earlier; thank you @karthik2804 for doing so.)

[macolso]

I would propose organizing the TOC by the 4 main documentation types: Tutorials, How-To Guides, Reference, and Concepts (referred to as Explanation in the screen shot)

The advantage of this approach is the user understands what type of help they will receive before opening the article, shortening their search. It also helps us avoid accidentally creating duplicative content or blurring the lines between documentation types. I took a stab of putting together a TOC based on this approach in Notion (if you don't have access, ping me)