DOCS-1916: Add overwrite fragment mods #2622

JessamyT · 2024-03-06T22:39:54Z

https://docs-test.viam.dev/2622/fleet/configure-a-fleet/#modify-the-config-of-a-machine-that-uses-a-fragment

viambot · 2024-03-06T22:40:55Z

Overall readability score: 55.58 (🟢 +0)

File	Readability
configure-a-fleet.md	70.03 (🟢 +0.93)

View detailed metrics

🟢 - Shows an increase in readability
🔴 - Shows a decrease in readability

File	Readability	FRE	GF	ARI	CLI	DCRS
configure-a-fleet.md	70.03	60.95	9.21	11.4	10.27	6.19
	🟢 +0.93	🟢 +0.2	🟢 +0.26	🔴 -0.1	🟢 +0.29	🟢 +0.06

Averages:

	Readability	FRE	GF	ARI	CLI	DCRS
Average	55.58	47.45	10.65	13.22	12.08	7.61
	🟢 +0	🟢 +0	🟢 +0	🟢 +0	🟢 +0	🟢 +0

View metric targets

Metric	Range	Ideal score
Flesch Reading Ease	100 (very easy read) to 0 (extremely difficult read)	60
Gunning Fog	6 (very easy read) to 17 (extremely difficult read)	8 or less
Auto. Read. Index	6 (very easy read) to 14 (extremely difficult read)	8 or less
Coleman Liau Index	6 (very easy read) to 17 (extremely difficult read)	8 or less
Dale-Chall Readability	4.9 (very easy read) to 9.9 (extremely difficult read)	6.9 or less

nataliajacobowitz

This is great! LGTM. @piokasar Would be great for you to take a look too to see if this looks good and if there are any other cases you think are important to show.

piokasar · 2024-03-07T02:14:22Z

LGTM! Thank you for doing this!!

skyleilani

This is so clean. Really great to read, thank you!!

docs/fleet/configure-a-fleet.md

skyleilani · 2024-03-07T15:35:56Z

docs/fleet/configure-a-fleet.md

@@ -78,7 +78,262 @@ For an example of adding a fragment to a machine, see the [Add a Rover Fragment
 ## Modify the config of a machine that uses a fragment

 When you modify a fragment, those changes are pushed to all machines that use that fragment.
-If you need to modify the config of just one machine that uses a fragment you can do the following:
+If you need to modify the config of just one machine that uses a fragment you have two options:


Suggested change

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

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

Suggestion for clarity

I think singular sounds a little bit more formal than necessary and I think just one makes sense--I'd like to keep as-is if that's okay!

Makes complete sense!

docs/fleet/configure-a-fleet.md

skyleilani · 2024-03-07T15:50:05Z

docs/fleet/configure-a-fleet.md

+5. Add any mods you'd like to apply.
+   Click to view each example:
+
+   {{%expand "Change the name and attributes of a component" %}}


These are so beautiful I teared up a bit.

docs/fleet/configure-a-fleet.md

skyleilani · 2024-03-07T16:00:43Z

docs/fleet/configure-a-fleet.md

+   - Takes whatever the pin number for pin `b` was and assigns that value to the DIR pin.
+     Deletes the `pins.b` field.
+
+   _If you want to change the `name` of a component (for example, `motor1`), use `$set`, as shown in the change the name of a component example.


Suggested change

_If you want to change the `name` of a component (for example, `motor1`), use `$set`, as shown in the change the name of a component example.

_To change the `name` of a component (for example, `motor1`), use `$set`, as shown in the change the name of a component example.

Very optional suggestion for conciseness since there is more text in this section.

I'll swap the order of these two sentences--see below

skyleilani · 2024-03-07T16:06:29Z

docs/fleet/configure-a-fleet.md

+     Deletes the `pins.b` field.
+
+   _If you want to change the `name` of a component (for example, `motor1`), use `$set`, as shown in the change the name of a component example.
+   `$rename` is for changing the key, not the value._


Suggested change

`$rename` is for changing the key, not the value._

`$rename` is for changing attributes' keys, not their values._

or

Suggested change

`$rename` is for changing the key, not the value._

`$rename` is for changing an attributes key, not its value._

Do you know if in the context of Viam $rename can still operate on multiple attributes simultaneously so that you can rename multiple keys?

I thought it could be nice to make it clear/reiterate that you're talking about an attribute key and value just for clarity, what do you think though?

Yes--if I understand your question correctly, the example here shows exactly that--two things being renamed simultaneously. I tested and it worked.

Yeah I can add that clarification. I'll also swap the order of these two italicized sentences, which I think will help with your comment above this too.

docs/fleet/configure-a-fleet.md

piokasar · 2024-03-07T19:36:09Z

docs/fleet/configure-a-fleet.md

+    {
+      "fragment_id": "abcd7ef8-fa88-1234-b9a1-123z987e55aa",
+      "mods": [
+        {


looking back it this - I think when the command is the same, it shouldn't be repeated - just have it as:

"$set": { "components.motor1.attributes.max_rpm": 1818, "components.motor1.attributes.pins.a": 30, "components.motor1.attributes.board": "local" }

Unless you were able to get it to work this way . Going to test this right now though to double check.

Yeah I think they may have to be stacked if the command is the same within the same fragment_mods entry - there's a duplicate key error in the json and it discards the second.

Screen.Recording.2024-03-07.at.2.49.40.PM.mov

Oh interesting! That looks a lot cleaner. I didn't try combining them--I only tried it repeated, which did seem to work also for me I thought! I'll update them.

oh interesting 🤔 I wonder why mine didn't that's odd

piokasar · 2024-03-07T19:52:51Z

docs/fleet/configure-a-fleet.md

+      "fragment_id": "abcd7ef8-fa88-1234-b9a1-123z987e55aa",
+      "mods": [
+        {
+          "$set": {


it would have to happen here as well

piokasar · 2024-03-07T19:54:19Z

docs/fleet/configure-a-fleet.md

+      "fragment_id": "abcd7ef8-fa88-1234-b9a1-123z987e55aa",
+      "mods": [
+        {
+          "$rename": {


stacking would have to be here too. Sorry I missed this earlier.
Also forgot to mention that the docs look really nice - thank you 😊

docs/fleet/configure-a-fleet.md

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

docs/fleet/configure-a-fleet.md

viambot · 2024-03-07T20:43:07Z

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

DOCS-1916: Add overwrite fragment mods

e42f72e

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

JessamyT requested a review from nataliajacobowitz March 6, 2024 22:41

nataliajacobowitz approved these changes Mar 6, 2024

View reviewed changes

piokasar approved these changes Mar 7, 2024

View reviewed changes

skyleilani approved these changes Mar 7, 2024

View reviewed changes

npentrel reviewed Mar 7, 2024

View reviewed changes

docs/fleet/configure-a-fleet.md Outdated Show resolved Hide resolved

piokasar reviewed Mar 7, 2024

View reviewed changes

JessamyT commented Mar 7, 2024

View reviewed changes

docs/fleet/configure-a-fleet.md Outdated Show resolved Hide resolved

Apply suggestions from code review

c130453

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

JessamyT commented Mar 7, 2024

View reviewed changes

docs/fleet/configure-a-fleet.md Outdated Show resolved Hide resolved

JessamyT commented Mar 7, 2024

View reviewed changes

docs/fleet/configure-a-fleet.md Outdated Show resolved Hide resolved

JessamyT commented Mar 7, 2024

View reviewed changes

docs/fleet/configure-a-fleet.md Outdated Show resolved Hide resolved

JessamyT added 3 commits March 7, 2024 12:23

Apply suggestions from code review

c0126b0

Update docs/fleet/configure-a-fleet.md

9c71691

Merge branch 'main' into 1916overwritefragments

aea0741

JessamyT merged commit 0ac496f into viamrobotics:main Mar 7, 2024
10 checks passed

JessamyT deleted the 1916overwritefragments branch March 7, 2024 20:48

sguequierre pushed a commit to sguequierre/docs that referenced this pull request Apr 25, 2024

DOCS-1916: Add overwrite fragment mods (viamrobotics#2622)

cdee10d

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

DOCS-1916: Add overwrite fragment mods #2622

DOCS-1916: Add overwrite fragment mods #2622

JessamyT commented Mar 6, 2024 •

edited

Loading

viambot commented Mar 6, 2024 •

edited

Loading

nataliajacobowitz left a comment

piokasar commented Mar 7, 2024

skyleilani left a comment

skyleilani Mar 7, 2024

JessamyT Mar 7, 2024

skyleilani Mar 7, 2024

skyleilani Mar 7, 2024

skyleilani Mar 7, 2024

JessamyT Mar 7, 2024

skyleilani Mar 7, 2024

JessamyT Mar 7, 2024

piokasar Mar 7, 2024

piokasar Mar 7, 2024

JessamyT Mar 7, 2024 •

edited

Loading

piokasar Mar 7, 2024

piokasar Mar 7, 2024

piokasar Mar 7, 2024

viambot commented Mar 7, 2024

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

	_If you want to change the `name` of a component (for example, `motor1`), use `$set`, as shown in the change the name of a component example.
	_To change the `name` of a component (for example, `motor1`), use `$set`, as shown in the change the name of a component example.

	`$rename` is for changing the key, not the value._
	`$rename` is for changing attributes' keys, not their values._

	`$rename` is for changing the key, not the value._
	`$rename` is for changing an attributes key, not its value._

DOCS-1916: Add overwrite fragment mods #2622

DOCS-1916: Add overwrite fragment mods #2622

Conversation

JessamyT commented Mar 6, 2024 • edited Loading

viambot commented Mar 6, 2024 • edited Loading

nataliajacobowitz left a comment

Choose a reason for hiding this comment

piokasar commented Mar 7, 2024

skyleilani 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

JessamyT Mar 7, 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

viambot commented Mar 7, 2024

JessamyT commented Mar 6, 2024 •

edited

Loading

viambot commented Mar 6, 2024 •

edited

Loading

JessamyT Mar 7, 2024 •

edited

Loading