Page in docs:
https://suborbital.github.io/docs/docs/what-is-webassembly/why-webassembly

This needs more context and a work-in-progress page in Notion.

https://suborbital.github.io/docs/compute/quickstart/client-libraries/nodejs

Use this library to easily interact with Compute's APIs.

Missing a link, should link to https://www.npmjs.com/package/@suborbital/compute

Things like a missing comma, a missing sentence terminating period, formatting issues.

Parts I've noticed:

• https://suborbital.github.io/docs/compute/quickstart/create-an-environment-token-with-subo, Compute environment would be called com.awesomeco See Fully-qualified function names for more information.
• https://suborbital.github.io/docs/compute/quickstart/client-libraries/nodejs#full-api, the description / args / result trio under each subheading is a run-on sentence, they should be formatted better

In the atmo / more info / background article there's a link to the SUFA design pattern documentation which currently links to https://blog.suborbital.dev/how-to-familiarize-yourself-with-a-new-codebase

I think it is supposed to link to https://blog.suborbital.dev/building-a-better-monolith? @cohix can you double check my assumption? :)

Related code change here: suborbital/e2core#145

We should get an initial documentation scaffolded for sat. The docs should contain the README content, and an appropriate structuring, during which we should discover the missing content requirements.

We should have information on how to run sat (baremetal/docker deployments), as well as some information about the one-shot runnable executor engine usecase.

We should consider how to implement versioned docs (that is, release documentation in sync with Atmo / SCN releases). While making documentation versions for all (earlier) releases is certainly important and useful for many reasons, it comes with a couple important pitfalls that need to be mitigated. A few of these:

• Search engine index de-sync (people arriving at earlier versions of the docs when searching for something)
• Atmo + SCN versioning needs (what should be the version in e.g. the URL, sync version numbers across Atmo / SCN, how to refer to a specific release etc.)

• Let's update Atmo will be gaining a secrets management system in 2021. ?

• Let's change By default, Rust will be used. To use Swift, pass --lang to instead use JavaScript as the alternative?

• Let's remove To start, Atmo supports handlers for HTTP requests, particulary designed to help building web APIs.

• The as and with clauses shown above will be discussed next. links to the 'Managing state' page, which is not actually next in the list.

• Let's change the Building a bundle page title to instead be Build your application

• Let's remove To learn how to operate Atmo in real-world scenarios.

• Let's change Atmo is still in early Beta, and as such should not yet be used for production workloads. to Atmo is in beta, and is suitable production workloads. If you're using Atmo in production, please reach out to us via [Discordlink] or [mailto:[email protected] link] so we can learn how you're using it!

• In the Embed bundle section, we say you can use a Dockerfile similar to this, but it should instead say you can use the Dockerfile that was created for your project by Subo.

• On the 'Handling requests' page, let's move 'state' to the bottom and not use it in the example at the top (things like URL and Method are more important)

• Maybe we should change 'HTTP Requests' to be 'HTTP client'? To differentiate it from handling requests. And GraphQL client to match

• I'm torn on Authentication, it feels like it should be up in the usage section.

• On the 'Accessing cache' page, let's link back to the 'Connections' page to show where they can configure Redis etc.

• Let's split up Sat into three pages: Using Sat, Building Sat, and Constellations.

Need to insert a release cadence page with details regarding

• How the release cycle is scheduled for each of the projects
• The actual cadence
• The release process

• Flaki and I had the same experience of wanting a simple app to deploy using Atmo and follow through the docs with
• I’d thought that was the example project would be, but the barrier to entry was consistently too high
  • Flaki and I are going to pair on reducing the barrier to entry and integrating the example project into the docs; e.g. documenting the Runnables in the example project
  • I’d love for this to actually create a proper little web app to give a sense of completion for the new user (maybe a longer-term goal)

Would it make sense to pin the docs repo to the main page on GitHub, alongside the pins for atmo, sat, and subo?

npm, yarn, pnmp

npm comes default with node installed. People who install yarn or pnpm have gone out of their way to deviate from the default, so the assumption is that they know how a given npm command looks like in their choice of package manager.

That means we could reduce noise by omitting command examples that relate to yarn or pnpm.

On the other hand that might make it harder for newer devs to work with the documentation especially if they were advised to install yarn as a first thing after installing node when they began their developer journey.

Currently "not all supported languages" in Reactr are created equal. There are differences between supported Runtime APIs, especially on preview/beta languages.

I would imagine such a "language support grid" to be similar to caniuse.com — with the rows of the table representing various Runtime API features, grouped by the API (that is, various methods of the req request handling API would be individually present), while the columns would be the supported languages (Tiny Go, JS/TS etc.).

The (potentially color-coded) cells would refer to the Reactr version in which a given API became available for use in the respective languages, and would present an opportunity for further notes/comments on support such as it is in the above linked page.

Another example of this pattern is the MDN browser compatibility tables which are also sourced from structured data.

• We should add per-language support tables for Reactr Runnable APIs (e.g. to the Language Support docs) to make it easier to expose this information to our users, but also to the developers themselves.

• We should also take steps to link the cells of missing support with tracking issues, and even automate the generation and maintenance of this information through automated sourcing of the API information from the relevant Reactr files and through automated testing.

These methods are supported but undocumented at least in some of the Reactr language bindings (e.g. JS/TS), and should be added to the docs where support exists.

On this page: https://docs.suborbital.dev/customizing-functions/custom-function-templates, towards the end there's a code snippet:

- name: SCC_TEMPLATES_REPO
  value: "{your fork}"

It's not clear what the value of your fork should be, or rather what the value should look like. Possibilities in my mind:

• simple user / reponame pair, for example javorszky/compute-templates
• full github url, for example: https://github.com/javorszky/compute-templates
• full gitlab url, for example: https://gitlab.com/gitlab-examples/bdowney-scratch/my-go-app5 (is Gitlab supported?)
• if it supports full urls, what's the default for only providing a username / repo pair?
• does it support git ssh urls? for example [email protected]:javorszky/compute-templates?

Content to include

• Different categories of contributions
• Links to different repositories with good-first-issues tags
• Contribution ladder

Currently every time we want to display a tabbed group with different content for every Reactr-supported language we have to write out the same structure manually using the <Tabs> built-in component.

This may make sense in certain places, but e.g. in API docs it gets onerous and error-prone.

It might make sense to provide a custom component for this which would enclose multiple fenced code blocks in different languages and automatically added the tabbed boilerplate.

E.g. this:

<ReactrLanguageTabs>
```rust
let mut foo = 0;
```
```typescript
let foo = 1;
```
</ReactrLanguageTabs>

would be expanded to the equivalent of:

<Tabs groupId="reactr-language">

<TabItem value="rust" label="Rust">
```rust
let mut foo = 0;
```
</TabItem>

<TabItem value="assemblyscript" label="AssemblyScript 🧪">
```typescript
let foo = 1;
```
</TabItem>

</Tabs>

This would actually come handy if we wanted to add features such as stability indicators (status: stable/preview/experimental/beta etc.) to the tabs themselves.

• For the "Intro to WebAssembly" section, switch the order of "History of the Internet" and "Why WebAssembly?" because the latter is a question most new users will have and the former could lose folks who think they should proceed through resources in the order given (whether we think they "should" think they need to do that doesn't matter; we don't want to lose—exclude—people over it).

• Also in the "Intro to WebAssembly" section: do we want to link to outside resources like these?

• #62

Cc: @flaki @cohix

Would be wonderful to have a reference page for all the Concepts and how they interconnect.

Could be an initial page in the Concepts section?

Happy to take lead on this!

Add content to the Suborbital ecosystem page about how they interlink with each other.
Good-to-have: Diagrammatic representation
Page to be changed: https://github.com/suborbital/docs/blob/main/website/docs/suborbital-ecosystem/the-suborbital-ecosystem.md

Information about the syntax of the handlers in a Directive is scattered across various pages of the Atmo docs. It would be nice to collect information about the various syntactic elements (steps, group, as, with...) on a single page.

I found this here and found it fascinating!

I wonder if we can make this more prominent/highlight it.

Maybe as a quote starting with Note?

This might even be more appropriate in the Directive page, and linked from the Managing State one.

I'd be happy to give this a try!

To me, the fact that the homepage of the docs doesn't have the navigation/sidebar/categories feels really odd, and I wonder if this artificial duality separating the "home page" from the "docs pages" makes sense.

@cohix on the other hand brought up another issue on Discord, whereas the Suborbital logo in the header feels superfluous when we have a large Suborbital logo on the top of the homepage itself. While this makes some sense, removing the header logo would degrade the consistency of the header (and would require hacking around the fact that the header is shared across all pages, so this would require a specific override in the theme based on the current document path).

I believe we may need to think through the information design and UX of the docs home page (and documentation at large) and avoid changing things on a whim, so this issue should serve as a place to discuss the way forward.

As per my previous Discord comment:

I really miss a 'Handler(s?)' option [from the Atmo→Concepts menu] in part, for completeness' sake, and in part because "state" is a not-too-often-referred to 'concept' as is, whereas handlers are the bread & butter of Atmo. It also happens that the Handler(s) doc would make sense after the Directive, and the state doc talks about handlers, basically, from a 'state' perspective. I wonder if it would make sense to rework it, and name this doc Handlers, explain the "state" as the implementation arising from handlers?

Case in point: in headless mode, there are no handlers and, thus, no "state", per se, either.

As per @ramonh's notes:

Handlers — Should this be covered under Concepts as well? I don’t know why I found myself getting stuck here when reading through.

We should figure out how to improve the exposure and taxonomy of these concepts.

Note: links might be pointing to private Suborbital Team resources and serve as reference, the relevant content have been reproduced in the issue text.

There should be a list of supported languages in Concepts → Runnables, e.g. under a new heading (so it can be directly referenced). We should list all languages with full support, beta or experimental support separately.

In Usage → Creating runnables we should reference this page for possible values of the --lang parameter.

This would include language-specific examples.

Configuration of capabilities granted to runnables has already landed for the Compute beta, but it wasn't properly documented. Some documentation exists in Compute (link above), but not in Atmo, however the same applies to Atmo in general.

Even the existing documentation in Compute is very terse and perhaps could be expanded, even with the current limited set of configuration options.

Currently many of the docs for various tools reinvent their own subo install steps, it would be best to consolidate these into one place and only keep reminders and links everywhere else to this canonical location.

#25 should take care of consolidating these in Atmo, but SCN seems to have its own, largely redundant take on this, as well.

We have a couple architecture diagrams in the Suborbital Miro workspace which would make sense to be exposed in the new docs. We should talk about what format would make sense (initially we can start with simple static SVG-s with perhaps some accompanying explanatory text, but later on more interactive/animated visualizations could be useful too)

Currently all pull requests deploy a preview through GitHub Actions at https://suborbital.github.io/docs/. This means that if there are multiple concurrent PRs in flight, the strongest (=last push) wins, this is far from ideal as we want to provide each PR with its own preview (especially when we start getting more outside contributors).

Resolving this might be as simple as adjusting the deployment folder, and Docusaurus' baseUrl accordingly, by including e.g. the PR's id or hash or similar unique identifier. We could also use Netlify or a similar service with branch PR-s but I think it would only take a small tweaking to enable the current GitHub Actions workflow to do as above described.

In the latter case, we should also make sure the GH Action returns the deployment URL in the PR CI details.

Currently the "Deploying Atmo" page has a copy-able code block containing a path that would need to be edited by the user, but doesn't mention this. We can change the path in the code block to be the current working directory.

It would be really useful to provide proper quickstart examples for all the Runnable API-s with each of the supported languages. We actually have a lot of these written already, so maybe we should explore how better to integrate these test/example files with the docs. We would need to figure out where these examples should live, but basically all examples in the docs should be automatically tested/verified that they work.

This closely relates to #23 as the tooling would need to know what version of the docs corresponds with what version of the runtime/Reactr to be able to associate the correct test files/examples with the right version of the docs.

The navigation bar currently contains too many accordions (collapsed levels of content), which makes it arduous and hard to navigate.

It was proposed that, as a first measure, some items on higher levels of nesting should be initially, or even permanently expanded:

The complexity of nesting may also be amended and simplified, if and where it makes sense, this is ongoing work as the content itself evolves.

https://atmo.suborbital.dev/usage/connections

Currently, Atmo can connect to NATS and Redis, and upcoming releases will include additional types such as databases and more.

vs further down

SQL databases and caches can be connected to Atmo to be made available to your Runnables using the Runnable API:
...
SQL database connections of type mysql and postgresql are available, and they are discussed in detail in the next section.

I think we can remove the "databases are coming" part from the top.

Moved from suborbital/e2core#115

https://atmo.suborbital.dev/getstarted/building-and-running

This section:

You can test the /hello route in a second terminal by sending a POST request with a body to it:

curl localhost:8080/hello -d 'from the Kármán line!'

I think it is a good idea to explicitly state that a successful test should return a 200 with the body returned to you, and everything else needs to be looked at.

Moved from suborbital/e2core#114

Improve the Getting Started guide for JavaScript/TypeScript in the Compute docs. Provide more detailed explanations and more clear-cut examples.

Also there seems to be perhaps a missing import here (configuration):

https://suborbital.github.io/docs/compute/quickstart/write-functions

• Alternatively, the Builder API can be used programmatically, if that better suits your use case. (see Step 4).

  Step 4 is connect your application.

• A quick way to try the editor is to use the REPL built into the Subo CLI introduced in Step 2.

  Step 2 is run compute locally

The steps aren't being referenced in the documentation on the target end, so just by reading step 4, we don't know what that means.

This is now implemented but remains undocumented in the Runnable API docs.

I did some digging around package the management system to use for this repo. The motivation here is reducing friction and making it easier to use the build the docs locally and contribute.

npm is available by default in node.js, installing the website dependencies on my computer takes ~10seconds, and 135 MB worth of dependencies are downloaded into node_modules.

yarn would normally cause extra trouble to install, but the latest versions of Node.js 14 and onwards makes its installation trivial thanks to corepack. This means that on all supported Node.js versions (v12 is unsupported and the LTS expires on April anyway) yarn can be enabled by the corepack enable command, without further platform-specific installation.

With this hurdle out of the way, the question is Yarn (2.0 plus) or Yarn Classic (1.x). Since 1.x is already deprecated I wouldn't add an extra dependency just for this, so I'd argue only modern Yarn should be considered.

Using the latest Yarn stable (3.1.1) the installation time is is around 6 seconds (a nice improvement) and the installed file module cache in the .yarn folder clocks in at 53 MB, this is a ~60% reduction compared to npm.

Yarn wants to have the module cache committed into the repository. While yarn fares much better in this regard than npm, this would come with a few drawbacks:

1. The module changes would eventually inflate/bloat the repository and increase the size of the checkout through old git objects downloaded to all clients despite being superseded since
2. Certain dependencies, like those containing executables and shell scripts cannot be stored in the compressed format and must be unplugged in order to function correctly. While these modules amount for less than 10 MB of all dependencies, they contain several hundred files and would make git operations considerably slower if checked into the repo.

Due to the above issues, I cannot recommend checking in yarn's cache into the GitHub repo without further testing, but perhaps using yarn should not be outright dismissed due to its other significant benefits. That said, I would argue that we should choose a single documented and supported method of building the docs and reflect this in the README, to reduce support overhead and complexity for contributions.

• On README.md under “Using this repository” it says you’ll be using Docusaurus, but under “Prerequisites” Git, Nodejs, and Yarn are listed as needing to be installed while Docusaurus is not. So I wondered for a minute whether I needed to install Docusaurus, but in fact Docusaurus “comes with” npm, which could be worth stating explicitly.

• - Under “Running the website locally” it says we need to run

  cd docs/website npm run build npm run serve

  But there’s a step missing, and it should instead read

  cd docs/website

  npm install (this was the missing step)

  npm run build

  npm run serve

• - In the image below, should it be clear that the text in the lower box will be generated by the terminal when subo build .finishes? It’s mostly clear, but the copy button in the corner throws it into question slightly. I think this is determined by some kind of styling infrastructure, but I'm not sure exactly where. But maybe there is/could be a distinct way to show code that isn’t being provided for the user to coy and use as input on their end, just for the sake of maximal clarity?) This probably happens in more places than just this one.
  

Docusaurus automatically adds PREV and NEXT page links, even across category boundaries, which sometimes misleads the readers of the documentation by implying a sequential connection between often unrelated pages.

We should make sure this does not happen by either removing these cross-links or ensuring that there is a continuity between the pages that are connected this way.

this page: https://suborbital.github.io/docs/compute/quickstart/write-functions

accessibility niggle: when linking to things, it's better to make the actual description of what we're linking to, rather than "click here"

Complete documentation for each of the URL parameters can be found here.

This might be better as

You can read more about the complete documentation for each of the URL parameters here.

source: https://webaim.org/techniques/hypertext/link_text

Each project should have a standardized link for the 'main page', such as:
/atmo/about
/sat/about
or just
/atmo
/sat

etc

The page this loads should include the project logo so it isn't just text.

https://suborbital.github.io/docs/compute/quickstart/run-compute-locally#repl

you will be prompted to start a REPL:

In my experience I'm dropped into the REPL without asking, or if the docs are referring to the Press enter to launch the local Compute REPL, then... I don't know what other choices I have besides hard exiting with a CTRL-C

The docs repo currently pulls in close to 150MB of object files on every git checkout. Not only that this will make it unnecessarily harder/slower for anyone to check out the repo and debug locally/contribute etc., but is also making GH Actions/builds ~30s slower, as that's how long it takes CI to clone the repo.

We should clean up the history and get rid of the unneeded files bloating the repo.

Use the reactr api descriptors to expand the Runtime API docs with the recently added languages (Tiny Go, JavaScript and TypeScript, Grain).