I don't know why, but the convention in these docs seems to be to use the "detached link" (aka "reference links") style:

I like [FOO].

[FOO]: http://example..com

While I understand that some people think this style is tidier, it has the following drawbacks, all of which have bitten me while attempting to work on these docs:

1. It is easy to orphan a link when the name and the target are so far apart
2. It is easy to accidentally override a link by re-declaring the reference between the initial usage and the intended reference
3. It is hard (and interruptive of flow) to see a link and then figure out where it goes. Sometimes it requires scrolling far down in the doc, losing one's place in the editorial flow
4. To stay in flow, one may choose not to look up the link (e.g. "Oh, [FOO] must go to the Foo homepage") when in fact that assumption is wrong
5. It is highly subjective where the references should go, and consequently it is hard to track down where to find them.

I understand using that syntax if you have a canonical (and small) set of URLs that need to be re-used... but to do all URLs this way feels like it causes significant editorial pain (at the risk of increased inaccuracy). Are there good reasons to keep this style, or can we use inline links instead?

in Boot Hippo, we give the user the choice between WAGI and WAGI.NET. We should NOT be giving the user any choice. Instead we should move that to the topic guides as "Selecting a Scheduler".

We should document how to spin up Hippo with nomad. Both locally, and on AWS.

https://docs.hippofactory.dev/intro/running-locally/

$ git clone https://github.com/deislabs/hippo
$ cd hippo/src/Hippo
$ dotnet restore
$ npm run build
$ export BINDLE_URL=http://localhost:8080/v1
$ dotnet run

It should be

$ git clone https://github.com/deislabs/hippo
$ cd hippo/
$ dotnet restore
$ export BINDLE_URL=http://localhost:8080/v1
$ dotnet run --project=src/Web/Web.csproj

Or... at least that's what I got to work... I don't really know what I'm doing. I just read the .sln file and guessed

there's a bit of a disconnect in the documentation. The docs first ask you to install the CLI tools, then boot hippo, then deploy an application using the CLI tools in the first step.

This should be streamlined to two workflows:

1. Quickstart for the server administrator - "boot hippo"
2. Quickstart for the developer - "install cli tools and deploy your first application"

The DataSeeder has now been removed; we need to reflect that in to docs. The user must now register an account for the first time.

In the docs here, it says to cd hippo/Hippo: https://docs.hippofactory.dev/intro/running-locally/

I think it might be hippo/src/Hippo... or maybe just hippo.

The current Boot Bindle docs says:

To start the compiled server, simply run bindle-server. If you would like to see the available options, use the --help command.

This is surrounded by various shell snippets that are part of the "boot" process.

It might be more clear to explicitly include a shell snippet to start the "bindle-server", I.e.

$ bindle-server

I noticed editing the quickstart guide that there are a lot of version numbers hardcoded into the text. An that requires a somewhat tricky update process, in which one must manually search-and-replace (and which causes more trouble when two different dependencies happen to incidentally have the same version number, so global fifnd-and-replace doesn't work).

Is there a way we could write a shortcode or something that would substitute, e.g., bindle-current-version with 0.4.1?

One of the users pointed out there is no documentation on whether Hippo apps can create outbound HTTP requests.
We should add a note in the docs.

To help us remember the meaning of app name, app ID, storage ID, revision selection strategy, range rule, domain, etc.

All the instructions/examples assume linux/mac os

The text inconsistently uses styles for referencing code-ish artifacts. Sometimes env vars are left unstyled. Sometimes they are stilled. Frequent conventions elsewhere suggest that using a CODE style is appropriate. Similarly, binary names and URLs should have consistent styling.

Calling hugo serve from the root causes the image URLs to be broken:

Looks like the image URLs are hard-coded to /images/hippo.png, but they should be served from /hippo/images/hippo.png

Eventually I'd like to split the docs into two groups: users and administrators.

Administrators are the individuals who maintain the infrastructure necessary to host applications. They are the ones installing, upgrading, and maintaining their own instance of hippo-server. They may also be responsible for administrative tasks like registering new accounts or writing new "helper tools" using the API as a reference guide. They want to know how to upgrade hippo-server, how to query the database, domain/TLS configuration, and how hippo-server communicates with nomad. They may also want to know how to handle Disaster Recovery (DR) scenarios.

Users are individuals who interact with the Hippo CLI. They are the ones creating applications, setting up release channels, inviting members to collaborate on an application, uploading apps to bindle, etc. They want to know what a HIPPOFACTS file does, how to register an account, create an application, and upload their source code. They may also want to know how to ensure other users cannot see their apps, or how to add other users to collaborate on their app. They may also want to know how to set up snapshots or advanced release channel configuration.

Right now the quickstart documentation tried to cover both bases by asking the user to install hippo, boot hippo-server, and create an app. I'd like to make that focused purely on the "User", and move the "boot hippo-server" guide to a separate section of the documentation.

Looking at the navigation pane, it is very difficult to tell which topics are nested under each topic because the indentation is incredibly subtle:

We should either make the indentation more pronounced, or perhaps embolden the main topics to make them stand out.