DOCS-2550: Add from one machine to many how-to #3201

JessamyT · 2024-08-06T22:53:31Z

Icons are stand-ins; could replace with more screenshots, and I'm seeing if Cristina has something similar if we want icons not screenshots

https://docs-test.viam.dev/3201/use-cases/one-to-many/

npentrel · 2024-08-07T11:53:19Z

docs/use-cases/one-to-many.md

+
+{{< table >}}
+{{% tablestep link="/configure/" %}}
+{{<imgproc src="/use-cases/one-to-many/config.png" resize="700x" class="fill alignleft" style="max-width: 250px" declaredimensions=true alt="Configuration builder UI">}}


This is an interesting approach but the screenshots are too small to be useful. If Cristina can create something that's great, if not I think use the full screenshots and add them in each step rather than to the side. Like in https://docs-test.viam.dev/3201/use-cases/configure/.

Alternatively what we could do is keep these as small screenshots and make them clickable to expand

#3206 adds functionality for it either way

docs/use-cases/one-to-many.md

npentrel · 2024-08-07T11:57:25Z

docs/use-cases/one-to-many.md

+{{<imgproc src="/use-cases/one-to-many/noun-reset.svg" class="fill alignleft" style="max-width: 100px"  declaredimensions=true alt="Reset to fragment">}}
+**2. (Optional) Revert fragment modifications**
+
+When you make edits to fields in your machine's config, a top-level section called `"fragment_mods"` is added to your JSON config with [update operators](https://www.mongodb.com/docs/manual/reference/operator/update/positional/#---update-) that modify each field you edit.


Please check Natalia's email on "overwrite fragments". I believe this has a UI now

Yes, it does, and I have them use the UI in step 1 but didn't realize there was a revert button because I didn't see it yesterday :D Yay!

npentrel

Good start. Just need to tidy up images and overwrites

docs/use-cases/one-to-many.md

docs/fleet/fragments.md

JessamyT · 2024-08-07T23:24:36Z

docs/fleet/fragments.md

@@ -175,170 +130,177 @@ This example assumes the fragment with ID `abcd7ef8-fa88-1234-b9a1-123z987e55aa`
 5. Add any update operators you'd like to apply to the fragment to the `mods` section.
   Click to view each example:

-   {{< expand "Change the name and attributes of a component" >}}
-   This example uses [`$set`](https://www.mongodb.com/docs/manual/reference/operator/update/set/#mongodb-update-up.-set) to make the following changes to the attributes of a motor named `motor1`:
+{{< expand "Change the name and attributes of a component" >}}


Note to reviewers: I didn't change any of the expander content, just un-indented to fix formatting bug after putting this into tabbed content

npentrel · 2024-08-07T23:33:38Z

docs/fleet/fragments.md

@@ -9,6 +9,10 @@ aliases:
  - /fleet/configure-a-fleet/
 ---

+{{< cards >}}


I think this needs to have some intro

eh?

Suggested change

{{< cards >}}

_This page contains reference information.

For a how-to guide, click here:_

{{< cards >}}

Or, a la data capture:

Suggested change

{{< cards >}}

Get started with a how-to guide or keep reading for more details.

{{< cards >}}

I think the second but maybe after line 39?

Okay. Adding a heading back in too for less confusion.

docs/fleet/fragments.md

npentrel · 2024-08-07T23:38:28Z

docs/fleet/fragments.md

 - Copy and paste the contents of the fragment, remove the link to the fragment itself, then modify the config as needed.
  - If you use this method, future updates to the fragment _will not_ be automatically pushed to your machine.


I think possibly this is not an option we should highlight. We only did this as a workaround I think. @nataliajacobowitz what do you think?

npentrel · 2024-08-07T23:40:43Z

docs/fleet/fragments.md

 {{% alert title="Support Notice" color="note" %}}

 `fragment_mods` are _not_ supported for the modification of [trigger](/configure/triggers/) configuration.
 You can create a trigger with a fragment but you cannot modify it with `fragment_mods`.

 {{% /alert %}}

-To configure fragment mods:
+### Use `fragment_mods`


Suggested change

### Use `fragment_mods`

### Overwrite fragments to add machine-specific modifications

I think overwrites is what the feature is called rather than fragment_mods. @nataliajacobowitz - thought?

@JessamyT elet's move forward with overwrites please. Either the above or this:

Suggested change

### Use `fragment_mods`

### Overwrite fragment fields

In fact you could also remove this and the revert fragment mods titles.

docs/use-cases/one-to-many.md

npentrel · 2024-08-07T23:48:00Z

docs/use-cases/one-to-many.md

+
+{{% /tablestep %}}
+{{% tablestep %}}
+{{<imgproc src="/use-cases/one-to-many/trash-can.svg" class="fill alignleft" style="max-width: 50px" declaredimensions=true alt="Delete">}}


This icon seems a different size to the other one.

yes because the line weights are very different. the larger one is from Cristina and has a much lighter weight to it so making that one small makes it almost disappear. We don't have all the icons that would be useful, but in the interest of moving forward I thought better to work with what we have.

I can just take out all the icons and have no images on the non-screenshot steps if you prefer?

I think it looks fine on mobile but untidy on desktop. Why don't you follow the pattern you've established and take a picture of the delete menu item on a configuration panel?

npentrel · 2024-08-07T23:48:31Z

Good changes, this is getting close. Thanks for the revisions

npentrel · 2024-08-08T16:23:20Z

docs/use-cases/one-to-many.md

+
+{{< table >}}
+{{% tablestep %}}
+{{<imgproc src="appendix/try-viam/rover-resources/fragments/fragments_list.png" resize="800x" class="fill alignleft" style="max-width: 300px" declaredimensions=true alt="Add fragment">}}


I think this should have the imgzoom class

npentrel · 2024-08-08T16:25:18Z

docs/use-cases/one-to-many.md

+
+{{% /tablestep %}}
+{{% tablestep %}}
+{{<imgproc src="/use-cases/one-to-many/trash-can.svg" class="fill alignleft" style="max-width: 50px" declaredimensions=true alt="Delete">}}


I think it looks fine on mobile but untidy on desktop. Why don't you follow the pattern you've established and take a picture of the delete menu item on a configuration panel?

npentrel · 2024-08-08T16:28:48Z

docs/use-cases/one-to-many.md

+
+{{< table >}}
+{{% tablestep link="/fleet/fragments/#modify-the-config-of-a-machine-that-uses-a-fragment" %}}
+{{<imgproc src="/use-cases/one-to-many/edit.svg" class="fill alignleft" style="max-width: 50px"  declaredimensions=true alt="Edit">}}


And then here maybe show a picture of the edits?

Mm but they won't see this unless they click advanced... I'll add mention of that

npentrel · 2024-08-08T16:29:56Z

docs/fleet/fragments.md

@@ -9,6 +9,10 @@ aliases:
  - /fleet/configure-a-fleet/
 ---

+{{< cards >}}


I think the second but maybe after line 39?

npentrel · 2024-08-09T12:33:39Z

docs/use-cases/one-to-many.md

+
+{{< table >}}
+{{% tablestep link="/fleet/fragments/#modify-the-config-of-a-machine-that-uses-a-fragment" %}}
+{{<gif webm_src="/how-tos/fragment-overwrite.webm" mp4_src="/how-tos/fragment-overwrite.mp4" alt="A robot drawing a heart" max-width="500px" class="aligncenter" >}}


that's very pretty

npentrel · 2024-08-09T12:38:03Z

docs/fleet/fragments.md

 If you need to modify the config of just one machine that uses a fragment, you have two options:

 - Use `fragment_mods` in your machine's config to overwrite certain fields of the fragment.
 - Copy and paste the contents of the fragment, remove the link to the fragment itself, then modify the config as needed.
  - If you use this method, future updates to the fragment _will not_ be automatically pushed to your machine.


Let's just remove it please. The old way was a hack. I am reasonably certain we no longer want to do this:

Suggested change

If you need to modify the config of just one machine that uses a fragment, you have two options:

- Use `fragment_mods` in your machine's config to overwrite certain fields of the fragment.

- Copy and paste the contents of the fragment, remove the link to the fragment itself, then modify the config as needed.

- If you use this method, future updates to the fragment _will not_ be automatically pushed to your machine.

If you need to modify the config of one or a few machines that use a fragment, you can overwrite fields of the fragment.

Please also remove https://docs-test.viam.dev/3201/fleet/fragments/#copy-and-paste-method

npentrel

Please accept the remaining suggestions and then merge. Thank you - this looks great

Co-authored-by: Naomi Pentrel <[email protected]>

viambot · 2024-08-09T17:45:12Z

You can view a rendered version of the docs from this PR at https://docs-test.viam.dev/3201

viambot added the safe to build This pull request is marked safe to build from a trusted zone label Aug 6, 2024

npentrel reviewed Aug 7, 2024

View reviewed changes

docs/use-cases/one-to-many.md Outdated Show resolved Hide resolved

npentrel reviewed Aug 7, 2024

View reviewed changes

docs/use-cases/one-to-many.md Show resolved Hide resolved

npentrel reviewed Aug 7, 2024

View reviewed changes

docs/fleet/fragments.md Outdated Show resolved Hide resolved

JessamyT force-pushed the 2550onetomany branch from d64c834 to c28afda Compare August 7, 2024 23:20

JessamyT mentioned this pull request Aug 7, 2024

DOCS-1915: Revert changes for fragments #3215

Closed

JessamyT commented Aug 7, 2024

View reviewed changes

JessamyT requested a review from npentrel August 7, 2024 23:25

npentrel reviewed Aug 7, 2024

View reviewed changes

npentrel reviewed Aug 8, 2024

View reviewed changes

JessamyT requested a review from npentrel August 8, 2024 19:17

JessamyT force-pushed the 2550onetomany branch from e524350 to fd22b26 Compare August 8, 2024 19:31

npentrel reviewed Aug 9, 2024

View reviewed changes

npentrel approved these changes Aug 9, 2024

View reviewed changes

JessamyT force-pushed the 2550onetomany branch from fd22b26 to 652f288 Compare August 9, 2024 16:55

JessamyT and others added 8 commits August 9, 2024 10:39

DOCS-2550: Add from one machine to many how-to

3459c73

Apply suggestions from code review

8ad3424

Co-authored-by: Naomi Pentrel <[email protected]>

Address Naomi feedback etc

15c0f78

de-duplicate

a2d6537

Apply suggestions from code review

2129193

Co-authored-by: Naomi Pentrel <[email protected]>

Address latest feedback and add GIF

2b8b920

linter

bc7623c

Address feedback

abc9fc1

mod to overwrite

f6b17e1

JessamyT force-pushed the 2550onetomany branch from c343e62 to f6b17e1 Compare August 9, 2024 17:39

JessamyT merged commit 6e3d842 into viamrobotics:main Aug 9, 2024
8 checks passed

JessamyT deleted the 2550onetomany branch August 9, 2024 17:52

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

DOCS-2550: Add from one machine to many how-to #3201

DOCS-2550: Add from one machine to many how-to #3201

JessamyT commented Aug 6, 2024 •

edited

Loading

npentrel Aug 7, 2024

npentrel Aug 7, 2024

npentrel Aug 7, 2024

npentrel Aug 7, 2024

JessamyT Aug 7, 2024

JessamyT Aug 7, 2024

npentrel left a comment

JessamyT Aug 7, 2024

npentrel Aug 7, 2024

JessamyT Aug 7, 2024

JessamyT Aug 8, 2024

npentrel Aug 8, 2024

JessamyT Aug 8, 2024

npentrel Aug 7, 2024

npentrel Aug 7, 2024

npentrel Aug 9, 2024

npentrel Aug 9, 2024

npentrel Aug 7, 2024

JessamyT Aug 7, 2024

npentrel Aug 8, 2024

npentrel commented Aug 7, 2024

npentrel Aug 8, 2024

npentrel Aug 8, 2024

npentrel Aug 8, 2024

JessamyT Aug 8, 2024

npentrel Aug 8, 2024

npentrel Aug 9, 2024

npentrel Aug 9, 2024

npentrel Aug 9, 2024

npentrel left a comment

viambot commented Aug 9, 2024

		- Copy and paste the contents of the fragment, remove the link to the fragment itself, then modify the config as needed.
		- If you use this method, future updates to the fragment _will not_ be automatically pushed to your machine.

	### Use `fragment_mods`
	### Overwrite fragments to add machine-specific modifications

DOCS-2550: Add from one machine to many how-to #3201

DOCS-2550: Add from one machine to many how-to #3201

Conversation

JessamyT commented Aug 6, 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

npentrel left a 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

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

npentrel commented Aug 7, 2024

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

npentrel left a comment

Choose a reason for hiding this comment

viambot commented Aug 9, 2024

JessamyT commented Aug 6, 2024 •

edited

Loading