Adding Images to Orchestration Docs #1238

amessbee · 2024-10-09T13:30:45Z

Here are the changes:

Adding an orchestration contract architecture graphic.
Adding a graphic with potential connections between chains established through Agoric Orchestration.
Updating sequence diagrams to use mermaid code directly in markdown.
Removing unused assets.

cloudflare-workers-and-pages · 2024-10-09T13:31:48Z

Deploying documentation with Cloudflare Pages

Latest commit:	`a15322c`
Status:	✅ Deploy successful!
Preview URL:	https://a93bea8a.documentation-7tp.pages.dev
Branch Preview URL:	https://ms-add-orch-images.documentation-7tp.pages.dev

View logs

dckc · 2024-10-09T16:01:51Z

main/guides/orchestration/index.md

@@ -10,6 +10,10 @@ The Agoric Orchestration API sits on top of Agoric’s novel VM that provides th

 Agoric’s Orchestration APIs simplify controlling accounts on remote chains, moving assets, and using capabilities on any chain the API reaches.

+<br/>
+<img src="./assets/orch_arch.svg" width="125%" />
+<br/>


Nice figure. I'd like to see it right after the 1st paragraph (ending "novel cross-chain-focused products.")

Also, how do we maintain it? Is this .svg file the editable source form? What tool did you use to create it?

@dckc I created the original image using latex in ipe tool, and yes this was SVG.

As per offline comments by @toliaqat I have updated the image with a new version, and moved it to how-orchestration-works page. This image uses the original source image from Agoric Orchestration Docs document and was created using Canva online editor for which SVG is not available.

Canva? I found it in some Google slides. Here's an SVG export:

@dckc can you update the text in "User Story" box as per the image mudassir uploaded, and reupload the SVG?

I don't think svg vs png is a debate that should delay improving docs. We already have both kinds of images in the repo and they solve the problem at hand. Optimizing the format should come when we have learned enough after many iterations and have nothing else to improve.

... We already have both kinds of images in the repo and they solve the problem at hand.

Yes; we use .png for screenshots and, until now, we used .svg for diagrams.

Optimizing the format should come when we have learned enough after many iterations and have nothing else to improve.

So only after many iterations we should consider accessibility? That's not a position I'm prepared to support.

https://www.ohchr.org/en/instruments-mechanisms/instruments/convention-rights-persons-disabilities#article-9

dckc · 2024-10-11T13:21:55Z

main/guides/orchestration/how-orch-works.md

@@ -15,6 +15,10 @@ To achieve these goals, several foundational technologies and protocols have
 been developed, with the [Inter-Blockchain Communication (IBC) protocol](https://ibcprotocol.org/) being
 one of the most prominent.

+<br/>
+<img src="./assets/orch_contract_arch.png" width="100%" />


any particular reason to switch from .svg to .png? .svg is more accessible - the text is searchable and selectable

I think free version of Canva does not let you download SVG.

Back to SVG again for that image by converting the source slide you linked. There is another image on the landing page now (in PNG for now). I would probably tinkering a bit more, and perhaps add one more image too.

the text is searchable and selectable

@dckc how is the text searchable and selectable in the SVG image? I cannot do that in your uploaded SVG. I could not find DEX in the source of your image as well.

I thought I already fixed that?

https://8abcef3f.documentation-7tp.pages.dev/guides/orchestration/how-orch-works.html

toliaqat

@amessbee please remove images from the PR that are not needed anymore. For example: main/guides/orchestration/assets/orch_arch.svg

github-actions · 2024-10-14T04:06:53Z

Cloudflare deployment logs are available here

amessbee · 2024-10-14T11:30:50Z

@dckc @mujahidkay @toliaqat I am adding a vite plugin for mermaid that renders diagrams from within markdown and seems to work fine. This will save us from keeping both .mmd source file and the .svg graphic file and we can directly add the mermaid code to the markdown. I have updated the sequence diagram on Orchestration landing page - never mind rest of the mess on that page for now. I will update docs wherever we are using mermaid code unless there is a reason not to.

mujahidkay · 2024-10-14T12:54:09Z

main/.vitepress/config.mjs

@@ -1,8 +1,9 @@
 import { defineConfig } from 'vitepress';


this import is not needed anymore

mujahidkay · 2024-10-14T13:07:00Z

main/guides/orchestration/index.md

@@ -10,6 +10,10 @@ The Agoric Orchestration API sits on top of Agoric’s novel VM that provides th

 Agoric’s Orchestration APIs simplify controlling accounts on remote chains, moving assets, and using capabilities on any chain the API reaches.

+<br/>
+<img src="./assets/chains4.png" width="100%" />


nit: appropriate filename chains.png should be fine

mujahidkay · 2024-10-14T13:09:48Z

package.json

@@ -67,10 +67,12 @@
    "eslint-plugin-prettier": "^5.2.1",
    "glob": "7.1.7",
    "import-meta-resolve": "^2.2.2",
+    "mermaid": "^11.3.0",


we also want to probe agoric-sdk CI against this branch. This is to avoid any underlying package used by these new packages to break it (it's broken right now so we may have to wait for #1240 to merge and then rebase)

toliaqat · 2024-10-14T19:09:32Z

@amessbee I really like the mermaid code and rendering package—it’s great that it allows users to select and search text on the page. Thanks for adding that! However, I would have preferred it as a separate PR so we could review and merge the graphic and mermaid PRs independently.

amessbee · 2024-10-15T12:31:39Z

@amessbee I really like the mermaid code and rendering package—it’s great that it allows users to select and search text on the page. Thanks for adding that! However, I would have preferred it as a separate PR so we could review and merge the graphic and mermaid PRs independently.

Of course. Created a separate branch - here is PR #1243

mujahidkay

Good addition to the docs!

Kindly update branch and re-verify before merging.

amessbee force-pushed the ms/add-orch-Images branch from d918108 to f2e94df Compare October 9, 2024 13:31

dckc reviewed Oct 9, 2024

View reviewed changes

dckc reviewed Oct 11, 2024

View reviewed changes

toliaqat reviewed Oct 12, 2024

View reviewed changes

amessbee force-pushed the ms/add-orch-Images branch 3 times, most recently from 026a281 to 4fae29d Compare October 14, 2024 12:54

amessbee marked this pull request as ready for review October 14, 2024 12:54

amessbee requested a review from mujahidkay October 14, 2024 12:54

mujahidkay reviewed Oct 14, 2024

View reviewed changes

amessbee force-pushed the ms/add-orch-Images branch from 4fae29d to 729b802 Compare October 14, 2024 13:32

amessbee requested a review from mujahidkay October 16, 2024 06:37

mujahidkay approved these changes Oct 16, 2024

View reviewed changes

amessbee force-pushed the ms/add-orch-Images branch 2 times, most recently from 1097ba5 to 10f5a0c Compare October 16, 2024 09:56

mujahidkay and others added 2 commits October 16, 2024 15:07

chore: orchestration graphics update

67ec59e

chore: update chain graphics

a15322c

amessbee force-pushed the ms/add-orch-Images branch from 10f5a0c to a15322c Compare October 16, 2024 10:08

amessbee merged commit 6e2685c into main Oct 16, 2024
6 checks passed

amessbee deleted the ms/add-orch-Images branch October 16, 2024 13:25

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Adding Images to Orchestration Docs #1238

Adding Images to Orchestration Docs #1238

amessbee commented Oct 9, 2024 •

edited

Loading

cloudflare-workers-and-pages bot commented Oct 9, 2024 •

edited

Loading

dckc Oct 9, 2024

dckc Oct 11, 2024

amessbee Oct 11, 2024 •

edited

Loading

dckc Oct 11, 2024

toliaqat Oct 11, 2024

toliaqat Oct 12, 2024

dckc Oct 16, 2024

dckc Oct 11, 2024

dckc Oct 11, 2024

amessbee Oct 11, 2024

toliaqat Oct 11, 2024

amessbee Oct 12, 2024

toliaqat left a comment

github-actions bot commented Oct 14, 2024 •

edited

Loading

amessbee commented Oct 14, 2024 •

edited

Loading

mujahidkay Oct 14, 2024

mujahidkay Oct 14, 2024

mujahidkay Oct 14, 2024

toliaqat commented Oct 14, 2024

amessbee commented Oct 15, 2024

mujahidkay left a comment

Adding Images to Orchestration Docs #1238

Adding Images to Orchestration Docs #1238

Conversation

amessbee commented Oct 9, 2024 • edited Loading

cloudflare-workers-and-pages bot commented Oct 9, 2024 • edited Loading

Deploying documentation with Cloudflare Pages

Choose a reason for hiding this comment

Choose a reason for hiding this comment

amessbee Oct 11, 2024 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

toliaqat left a comment

Choose a reason for hiding this comment

github-actions bot commented Oct 14, 2024 • edited Loading

amessbee commented Oct 14, 2024 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

toliaqat commented Oct 14, 2024

amessbee commented Oct 15, 2024

mujahidkay left a comment

Choose a reason for hiding this comment

amessbee commented Oct 9, 2024 •

edited

Loading

cloudflare-workers-and-pages bot commented Oct 9, 2024 •

edited

Loading

amessbee Oct 11, 2024 •

edited

Loading

github-actions bot commented Oct 14, 2024 •

edited

Loading

amessbee commented Oct 14, 2024 •

edited

Loading