FEE-86 - add Roam user guide to share your ideas and research

apps/website/content/roam/use-cases/share-your-ideas-and-research.mdx

@@ -0,0 +1,229 @@
+---
+title: "Share your ideas & research"
+date: "2026-06-29"
+author: ""
+published: true
+---
+
+import Image from "next/image";
+import { Callout } from "nextra/components";
+
+You've built your graph, a work of beauty and insight. Now you're ready to share what you've learned.
+
+<Image
+  src="/docs/roam/roam-graph-ex03.png"
+  alt="roam graph"
+  width={1720}
+  height={1011}
+  className="docs-bordered-image"
+/>
+_Getting eyes on the prize_
+
+- [Sharing your discourse graph](#sharing-your-discourse-graph)
+- [Sharing your discourse canvas](#sharing-your-discourse-canvas)
+- [Drafting a manuscript from your discourse graph](#drafting-a-manuscript-from-your-discourse-graph)
+
+## Sharing your discourse graph
+
+Roam Research is cloud-hosted, and its web, desktop, and mobile clients have built-in collaboration features.
+
+To create a multiplayer graph with shared access and authorship, go to `Settings → Sharing` and enter the email addresses of the people you want to share your graph with. You can also set read/write access permissions here.
+
+<Image
+  src="/docs/roam/roam-share-settings.png"
+  alt="roam graph share"
+  width={993}
+  height={441}
+  className="docs-bordered-image"
+/>
+_Roam graph sharing settings_
+
+<Callout type="info" emoji="💡">
+  Sharing your graph shares all parts of your graph; there are no private pages
+  in a shared Roam graph.
+</Callout>
+
+You can share individual pages from your graph as Markdown or JSON files. These pages can be imported into another Roam graph (JSON is best for this) or read as text files (Markdown is best for this).
+
+<Image
+  src="/docs/roam/roam-share-settings.png"
+  alt="page export"
+  width={993}
+  height={441}
+  className="docs-bordered-image"
+/>
+_Exporting pages from your graph_
+
+You can also export the results of a query in a variety of human- and machine-readable formats.
+
+<Image
+  src="/docs/roam/share-query-result.png"
+  alt="query export"
+  width={850}
+  height={513}
+  className="docs-bordered-image"
+/>
+_Exporting query results_
+
+## Sharing your discourse canvas
+
+### Presenting your canvas
+
+Your canvas can be used to give a PowerPoint- or Figma-like visual overview of your work.
+
+You can start at your motivating question and move through your hypothesis to your experiments and their results, opening each node in the sidebar to show your audience relevant details.
+
+<Image
+  src="/docs/roam/roam-canvas-walkthrough.gif"
+  alt="canvas tour"
+  width={1911}
+  height={990}
+  className="docs-bordered-image"
+  unoptimized
+/>
+_Example canvas walkthrough_
+
+You can create a "presentation view" for your discourse nodes by adding the material or images you want to highlight at the top of the page. The first image on the page is automatically selected as the image that displays on the discourse canvas.
+
+<Callout type="info" emoji="💡">
+  You can modify your discourse templates to customize your presentation view.
+  Check out [this
+  tutorial](https://roamresearch.com/#/app/template-lab/page/NlmtT4SQa) in the
+  template lab graph for tips.
+</Callout>
+
+### Exporting your canvas
+
+You can export your canvas as JSON or as a static .png or .svg image.
+
+<Image
+  src="/docs/roam/roam-export-canvas.png"
+  alt="export canvas"
+  width={516}
+  height={281}
+  className="docs-bordered-image"
+/>
+_The canvas menu_
+
+<Callout type="info" emoji="✎">
+  It is not possible at present to export a "live" discourse canvas to another
+  graph.
+</Callout>
+
+### Coworking on your canvas
+
+Any canvas in your graph can be edited or viewed by anyone who has the appropriate permissions in your graph. The **cloud canvas** feature supports real-time multiplayer collaboration between members of your graph: a shared whiteboard session where you can see others' edits as soon as they appear.
+
+<Image
+  src="/docs/roam/cloud-canvas-toggle.png"
+  alt="cloud canvas setting"
+  width={516}
+  height={281}
+  className="docs-bordered-image"
+/>
+_Enabling the cloud canvas_
+
+The cloud canvas is useful for shared brainstorming or manuscript planning sprints.
+
+## Drafting a manuscript from your discourse graph
+
+### Using the canvas as a storyboard
+
+You can use the discourse canvas to organize your ideas for a paper. Your canvas lets you follow your train of thought from hypothesis formation to hypothesis testing, including the dead ends. You can see at a glance which sources (references) were crucial to the formulation of certain claims, and which informed the design of your experiments.
+
+If you're targeting a particular journal, you might find it helpful to spatially arrange your discourse nodes according to its manuscript submission format. This can give you a head start on the drafting stage.
+
+<Image
+  src="/docs/roam/draft-manu01.png"
+  alt="organizing an article"
+  width={815}
+  height={592}
+  className="docs-bordered-image"
+/>
+_Using canvas layers to organize article sections_
+
+The canvas layout can also be used to spot "gaps" in your argument at a glance, before Reviewer #2 rushes in to fill them with part of their oeuvre.
+
+<Image
+  src="/docs/roam/roam-graph-ex01.png"
+  alt="gap spotting"
+  width={1720}
+  height={1010}
+  className="docs-bordered-image"
+/>
+_Mind the gap: spotting unsupported claims before Reviewer #2_
+
+The canvas is also useful for selecting and arranging figures, particularly for deciding which images should be composed into figure panels, and which visual evidence is crucial enough to highlight in the main body of the text versus the supplementary information.
+
+<Image
+  src="/docs/roam/fig-panel01.png"
+  alt="figure panel"
+  width={1633}
+  height={517}
+  className="docs-bordered-image"
+/>
+_Details of the experiment can go in one section..._
+
+<Image
+  src="/docs/roam/fig-panel02.png"
+  alt="results panel"
+  width={1446}
+  height={794}
+  className="docs-bordered-image"
+/>
+_... and the results in another_
+
+### Arguing with your graph
+
+Your discourse nodes should be formulated as concisely as possible, but the rest of the page can be used to construct and elaborate your broader point. The example below links both **Evidence** and **Caveats** related to a **Claim**. In this discourse context, a _Caveat_ is an observation that weakens the claim without necessarily opposing it. Some caveats may be promoted to Evidence that _opposes_ a Claim after further investigation, others may become **Issues**: requests for additional analyses to clarify a point. Anticipating the most salient caveats to each of your claims is useful preparation for the review stage of your manuscript submission.
+
+<Image
+  src="/docs/roam/graph-arg01.png"
+  alt="CLM"
+  width={1004}
+  height={956}
+  className="docs-bordered-image"
+/>
+_An example of a claim with caveats_
+
+You can [modify your discourse graph templates](https://roamresearch.com/#/app/template-lab/page/NlmtT4SQa) to structure key information in a way that facilitates article writing later.
+
+<Image
+  src="/docs/roam/graph-arg02.png"
+  alt="EVD"
+  width={1371}
+  height={957}
+  className="docs-bordered-image"
+/>
+_An example of an evidence node with methods context_
+
+Discourse nodes are modular and composable, and you can reuse them across multiple projects. One strategy to maximize composability is to capture "evergreen" information in the node template and add project-specific context in the "log" section.
+
+<Image
+  src="/docs/roam/graph-arg03.png"
+  alt="notes section"
+  width={1699}
+  height={949}
+  className="docs-bordered-image"
+/>
+_A claim template with a "Notes" section for logging observations in the context
+of a specific project_
+
+## Exporting your graph
+
+You can export your entire discourse graph in a format suitable for import into another Roam Research graph by selecting "Export All" from the Roam Settings menu and choosing "msgpack." You can also export your graph as JSON or Markdown for import into other programs.
+
+<Image
+  src="/docs/roam/template-lab-export02.png"
+  alt="graph export"
+  width={500}
+  height={257}
+  className="docs-bordered-image"
+/>
+_Exporting your entire graph_
+
+## What else would you like to do?
+
+- [Build and utilize a personal knowledge base](/docs/roam/use-cases/build-utilize-personal-knowledge-base)
+- [Synthesize insights from the literature](/docs/roam/use-cases/synthesize-insights-from-literature)
+- [Track your projects and experiments](/docs/roam/use-cases/track-your-projects-and-experiments)