Update docs with guides and tutorials for blueprint

[jleibs]

What

Checklist

• I have read and agree to Contributor Guide and the Code of Conduct
• I've included a screenshot or gif (if applicable)
• I have tested the web demo (if applicable):
  • Using newly built examples: app.rerun.io
  • Using examples from latest main build: app.rerun.io
  • Using full set of examples from nightly build: app.rerun.io
• The PR title and labels are set such as to maximize their usefulness for the next release's CHANGELOG
• If applicable, add a new check to the release checklist!

• PR Build Summary
• Docs preview
• Examples preview
• Recent benchmark results
• Wasm size tracking

[github-actions]

Size changes

Name	main	5641/merge	Change
rrt-star.rrd	29.44 MiB	3.52 MiB	-88.04%

[nikolausWest]

There are some things I suggest fixing before merging but in general I think the content itself looks good. There are some bigger things I think we should address before the release but I'd be for a liberal approach to merging and then iterating rather than letting PRs linger too long.

There bigger things for me are:

High level organization

I'm not sure about the high level organization, i.e. what goes where. We originally set out to use the approach from https://documentation.divio.com/ with four types of documentation (tutorials, how-to guides, explanation, reference) but may have lost our way a bit over time.

Some pages feel quite long, which tends to make them harder to maintain. I wonder if that is because they are serving multiple purposes (e.g. both reference and how-to guide).

Missing pages

Reading through these pages it becomes clear we also a couple more pages such as:

• A reference page on available space views and visualizers
• A page about the conceptual model of "space views are deterministic views on data" -> "blueprint sets layout & local data transform". Should be placed under concepts and might be called something like "Blueprint and visualizers".
• A page about the heuristics
• A page about the execution model of the viewer (on each frame, query the blueprint database for what to draw, start drawing, where needed query the recording, etc)
• Probably most important, an overview page that orients the reader about how the pieces fit together (diagrams galore)

Related: we also need a blueprint section as part of the quick start guides.

Lacking context

These pages still mostly open assuming that the reader has the correct big picture concepts about what Rerun is in their mind, which is unlikely to be true for newcomers. There might be some reusable diagrams + orienting text snippet that we could sprinkle around to help new readers orient themselves.

[nikolausWest]

Have we established anywhere that heuristics run to automatically to determine an appropriate layout? This feels like a non obvious concept to start with and if we don't cover it elsewhere, perhaps it should be introduced here and even needs a page under "Configure the viewer"?

[jleibs]

What would go on that page other than the same statement made here: "the Rerun Viewer tries to do a reasonable job of using heuristics to automatically determine an appropriate layout given the data that you provide "

[nikolausWest]

I'm not sure about this title and if it goes in the "How to Guide" section. We currently have the other tutorials under getting started so that might be a better place for this (closest analogy seems like the Logging data in Python/Rust/C++). Given that, the title should probably be something in the style of:

Suggested change

	title: Blueprint API Tutorial
	title: Controlling the viewer from code (Blueprint API)

[jleibs]

that's a mouthful for the nav-bar

[jleibs]

I think we should be careful about overly conflating the nav-bar organization and the names for the types of pages we create. The divio model doesn't dictate that we must organize the nav-bar exclusively by type of document.

This seems like too much to be a part of getting-started. And likewise, getting started is more than just tutorials.

[nikolausWest]

This section starts to feel a bit like a reference which makes me wonder if the "How to Guides" section is the right place for this page at all. Also slightly worried this will be hard to keep up to date but perhaps it's hard to get around.

One suggestion would be to do something like list the things you can do and have a video showing a couple examples. Alternatively we could add a PR checkbox to update these videos on major UI updates or something like that.

[jleibs]

Yeah, I'm generally against videos for that reason... they are going to rot. Those of us on linux aren't even positioned to produce the content or keep it up-to-date since we can't do video screencaps in the same style as the mac software. I don't have a great solution.