User guide (2/2): documentation content by lynwilhelm · Pull Request #864 · AllenInstitute/biofile-finder

lynwilhelm · 2026-07-06T17:56:29Z

PR 2 of 2. Base is user-guide-engine (#863) so this diff shows only the documentation content — ~2,760 lines. GitHub will auto-retarget this to main once #863 merges.

What this PR is

The guide's actual documentation, layered onto the engine from #863. Almost entirely prose in JSX (content/*.tsx) plus screenshots — low-risk to review; skim for copy, links, and typos rather than logic.

content/about.tsx, app-information.tsx, getting-started.tsx, real-world-use-cases.tsx
content/index.ts expanded from the single engine seed to the full section list: About, Real world use, App information, Getting started, Other resources
Inline screenshots (grouping hierarchy/panel, querying filters/results, sharing URL, thumbnail grid), each with descriptive alt/ariaLabel text

Notable content

Overview "BFF and related tools" comparison table, refined per reviewer feedback to position BFF as a companion to (not a replacement for) other data repositories.
Getting started pages for creating a metadata file, nesting metadata columns, describing columns, and file/metadata provenance.
Real-world use cases and supplementary resources.

Image compression

The thumbnail grid was a 1.1 MB PNG; it's photographic, so PNG was the wrong format. Converted to JPEG (quality 85, full 2364px resolution retained) → 282 KB (~4× smaller, no downscaling, retina intact). Added the *.jpg module declaration for the import. Extended the webpack asset/resource loader (previously png-only) to match jpg/jpeg.

Testing

tsc --noEmit (web): passes
eslint on content files: passes
npm run test:web: 52 passing
husky pre-commit (eslint + prettier): passes
Manually verified in the running app: all five sections render, screenshots (including the converted JPEG thumbnail) display crisply, and the bundle compiles cleanly with the .jpg loader.
Content files are ported verbatim from the previously reviewed Lyndsay's User Guide Implementation #833; the only changes unique to this PR are restoring the full content/index.ts list and the thumbnail PNG→JPEG swap.

Review order

Review #863 (the engine) first. This content PR is a skim.

Original combined PR: #833 (kept for review history).

Second of two stacked PRs into user-guide-final. Adds the guide's documentation prose and expands the content list to all sections: About, Real world use, App information, Getting started, and the Other resources page already present from the engine PR. - content/about.tsx, app-information.tsx, getting-started.tsx, real-world-use-cases.tsx - content/index.ts expanded to the full section list - Inline screenshots (grouping, querying, sharing, thumbnails) - Compress the thumbnail grid from a 1.1 MB PNG to a 282 KB JPEG (photographic content; full 2364px resolution retained); add the *.jpg module declaration Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

The thumbnail was converted to JPEG; extend the asset/resource rule (png only) to also match jpg/jpeg so the bundle resolves the import. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

Follows the engine PR change removing the custom slugify helper. Anchor IDs (DocPage) and in-page anchor links (content) both use kebabCase, so they stay consistent. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

# Conflicts: # packages/web/src/components/UserGuide/content/index.ts

SeanDuHare · 2026-07-08T17:06:29Z

@aswallace Could you verify and rewrite any portion of the provenance information that is wrong or could use more information etc.?

SeanDuHare · 2026-07-08T20:44:51Z

+
+import { Page, PageSlug, SectionHeading } from "./types";
+
+// Note: "real-world-use-cases/other-examples" exists in this file but has no


I think this is untrue now

SeanDuHare · 2026-07-08T20:45:10Z

+                                    </td>
+                                    <td>Hours of scripting per query</td>
+                                </tr>
+                                {/* "Validate metadata" row — temporarily hidden


Is this an active TODO? If so, linking a ticket would be good. Otherwise, lets delete it and the corresponding section below.

SeanDuHare · 2026-07-08T20:48:56Z

+                        </p>
+                        <p>
+                            See:{" "}
+                            <a


Across all of these content pages where you create a relative link you can use the same <Link /> generation function you did in the previous PR instead of the regular <a /> tag.

Example

<Link to={userGuidePath( GroupSlug.OtherResources, PageSlug.StorageOptions )} >

BrianWhitneyAI · 2026-07-08T21:26:20Z

GitHub will auto-retarget this to main once #863 merges.

This is not currently true since 863 is pointed at another branch

aswallace

I'm currently only partway through reviewing, but wanted to open the first round of comments now to avoid overwhelm

aswallace · 2026-07-07T00:19:37Z

+                            aria-label="Scrollable comparison table"
+                        >
+                            <div className="ug-scroll-table">
+                                <table className="ug-table">


The auto-sizing is making the widths look a little uneven/arbitrary across tools, possibly could be one size fixed-width for all instead since the height does change

aswallace · 2026-07-07T00:21:23Z

+                body: (
+                    <>
+                        <p>
+                            BFF uses <strong>DuckDB</strong> — a high-performance analytical SQL


Should we link to the main DuckDB site here?

aswallace · 2026-07-08T21:10:06Z

+                                relationship is defined via a dataset column.
+                            </li>
+                        </ul>
+                        <h3>Simple example</h3>


Might be nice to show what the resulting graph would look like for this example

aswallace · 2026-07-08T21:20:39Z

+                        </p>
+                        <p>
+                            In BFF, once a provenance file is loaded, each file row in the file list
+                            will show a relationship indicator. Expanding a row reveals its linked


I don't think this paragraph is true atm, expecially @ "expanding a row reveals its linked parent or child entities"

aswallace · 2026-07-08T21:22:49Z

+                        </ul>
+                        <p>
+                            <a
+                                href={createCsvDataUri(PROVENANCE_SIMPLE_EXAMPLE_ROWS)}


we should also make sure to include an example that uses "self"

aswallace · 2026-07-08T21:27:05Z

+                                <tr>
+                                    <th>Use case</th>
+                                    <th>Key BFF actions</th>
+                                    <th>Time saved vs. manual</th>


Unsure about this column title since only the first listing actually references time

# Conflicts: # packages/web/src/components/UserGuide/content/index.ts

BrianWhitneyAI · 2026-07-08T22:01:07Z

Image compression
The thumbnail grid was a 1.1 MB PNG; it's photographic, so PNG was the wrong format. Converted to JPEG (quality 85, full 2364px resolution retained) → 282 KB (~4× smaller, no downscaling, retina intact). Added the *.jpg module declaration for the import. Extended the webpack asset/resource loader (previously png-only) to match jpg/jpeg.

This is an example of extra description content I would say is not useful.

BrianWhitneyAI · 2026-07-08T22:01:55Z

tsc --noEmit (web): passes
eslint on content files: passes
npm run test:web: 52 passing
husky pre-commit (eslint + prettier): passes

This is already relayed by the passing unit tests

- "user-supplied metadata" (avoid implying access to user data) - Remove comma in the Setup overview intro - Simplify the repetitive Columns description - Comma instead of em-dash in the provenance-importance paragraph Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

BrianWhitneyAI · 2026-07-08T22:06:29Z

+                                <span>Computational biologists</span>
+                            </li>
+                            <li>
+                                <span>Data engineers & platform teams</span>


what is a platform team?

BrianWhitneyAI · 2026-07-08T22:07:52Z

+                            <div className="ug-feature-card">
+                                <span>Format agnostic</span>
+                                <br /> BFF treats metadata as data (Parquet/CSV), not tied to any
+                                specific image format. By contrast, OMERO is deeply tied to


Adding in the contrast to OMERO here feels strange. Like an advertisement against a competitor

BrianWhitneyAI · 2026-07-09T15:46:10Z

+                                                <strong>Works Without a Server</strong>
+                                            </td>
+                                            <td>
+                                                Yes — runs entirely in-browser or as desktop app


Do we want to talk about the desktop app for this?

BrianWhitneyAI · 2026-07-09T15:48:56Z

+                                            <td>Yes — via OMERO.server with S3 backend</td>
+                                            <td>N/A</td>
+                                            <td>N/A</td>
+                                            <td>Yes — any HTTP-hosted Zarr</td>


no HTTPS here?

BrianWhitneyAI · 2026-07-09T15:49:53Z

+                                            <td>
+                                                <strong>Image Viewing</strong>
+                                            </td>
+                                            <td>Thumbnails; delegates to external viewers</td>


We do generate thumbnails

BrianWhitneyAI · 2026-07-09T20:18:38Z

+                        <iframe
+                            width="560"
+                            height="315"
+                            src="https://www.youtube.com/embed/RD2x4BFhWzY?si=a1ZPYrq-k2VVhCCc"


Is this a duplicate?

BrianWhitneyAI · 2026-07-09T20:23:03Z

            },
            {
-                test: /\.png/,
+                test: /\.(png|jpe?g)/,


lynwilhelm requested review from BrianWhitneyAI, SeanDuHare and aswallace as code owners July 6, 2026 17:56

lynwilhelm mentioned this pull request Jul 6, 2026

User guide (1/2): rendering engine, routing, and navigation #863

Open

Configure webpack asset loader to handle .jpg

955c108

The thumbnail was converted to JPEG; extend the asset/resource rule (png only) to also match jpg/jpeg so the bundle resolves the import. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

lynwilhelm mentioned this pull request Jul 6, 2026

Lyndsay's User Guide Implementation #833

Open

lynwilhelm and others added 6 commits July 7, 2026 13:45

Merge branch 'user-guide-engine' into user-guide-content

c85d9e5

Merge branch 'user-guide-engine' into user-guide-content

85324a5

Merge branch 'user-guide-engine' into user-guide-content

7fe7531

Swap slugify for lodash kebabCase in guide content

fc03e47

Follows the engine PR change removing the custom slugify helper. Anchor IDs (DocPage) and in-page anchor links (content) both use kebabCase, so they stay consistent. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

Merge branch 'user-guide-engine' into user-guide-content

4c3cadc

Merge branch 'user-guide-engine' into user-guide-content

39ceecc

# Conflicts: # packages/web/src/components/UserGuide/content/index.ts

SeanDuHare reviewed Jul 8, 2026

View reviewed changes

Merge branch 'user-guide-engine' into user-guide-content

04d0fc4

aswallace reviewed Jul 8, 2026

View reviewed changes

Merge branch 'user-guide-engine' into user-guide-content

0941bd2

# Conflicts: # packages/web/src/components/UserGuide/content/index.ts

BrianWhitneyAI reviewed Jul 9, 2026

View reviewed changes


		import { Page, PageSlug, SectionHeading } from "./types";

		// Note: "real-world-use-cases/other-examples" exists in this file but has no

Uh oh!

Conversation

lynwilhelm commented Jul 6, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

What this PR is

Contents

Notable content

Image compression

Testing

Review order

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

SeanDuHare Jul 8, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

SeanDuHare Jul 8, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

BrianWhitneyAI commented Jul 8, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

aswallace left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

BrianWhitneyAI commented Jul 8, 2026

Uh oh!

BrianWhitneyAI commented Jul 8, 2026

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

lynwilhelm commented Jul 6, 2026 •

edited

Loading

SeanDuHare Jul 8, 2026 •

edited

Loading

SeanDuHare Jul 8, 2026 •

edited

Loading

BrianWhitneyAI commented Jul 8, 2026 •

edited

Loading