DOCS-2481: Add motor how to #3036

skyleilani · 2024-06-18T19:18:03Z

This PR introduces a stylistically different approach from our other how-to pages. I am happy to make any changes as needed; this shortcode is a stylistic option I'm exploring.

expand-and-search.html
This new shortcode is similar to expand.html, but utilizes the <details> element rather than <div>. This allows users to use Cmd + F to search through the contents of the expandable steps even when they are collapsed. When the content is searched in this way, the relevant expandable section will automatically open.

Purpose
The reasons I am trying the implementation of this style is:

Focused Search
I think this approach benefits users who know exactly what they are looking for. For example, if a user already has configured a board and is looking for a specific function, such as simply going straight to controlling the motor, they can find it easily without sifting through steps they have already done.
Two high-level overviews
This approach also provides a high-level overview of the already quite high-level steps required to achieve functionality. I thought this could be helpful for understanding the overall process before diving into each step in detail.
Simplicity
This approach provides a page that users might not feel overwhelmed or discouraged by due to its simplicity, but that is very subjective.

viambot · 2024-06-18T19:19:16Z

Overall readability score: 53.04 (🟢 +0.03)

File	Readability
control-motor.md	80.23 (-)

View detailed metrics

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

File	Readability	FRE	GF	ARI	CLI	DCRS
control-motor.md	80.23	66.64	7.07	9.2	8.8	6.09
	-	-	-	-	-	-

Averages:

	Readability	FRE	GF	ARI	CLI	DCRS
Average	53.04	45.64	11.12	12.66	12.14	8.28
	🟢 +0.03	🟢 +0.03	🟢 +0.01	🟢 +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

npentrel

I like the format with the expanders.
I don't think this currently provides enough detail for people to accomplish this task if they've just created an account and haven't done anything else yet. I'm also a bit sceptical whether we can actually do this in 60 seconds, how do you feel about that? Do you think that premise makes sense?

docs/use-cases/control-motor.md

npentrel · 2024-06-18T21:54:33Z

layouts/shortcodes/expand-and-search.html

I'm not sure I understand the change here - Does this change anythign aside from the cursor pointer right? We can discuss changing this but then we should change the expand shortcode so that it gets changed everywhere for consistency.

This uses <details> and <summary> HTML elements instead of <div>. The browser automatically expands collapsed content when users search using Command + F.

This way users can search through content even when they have not expanded a section manually. In the original expand.html, collapsed content is not searchable by default, so users had to manually expand sections to search within them.

!!!!!!!!!!!!!
I didn't know that - that is so cool!! I wonder if we can even use that to make tabs searchable. Awesome!

Ohh I will definitely be trying this out today..!

makes me wonder whether we can also make them open up as we scroll through the page. But we can look into that separately

docs/use-cases/control-motor.md

npentrel · 2024-06-18T22:10:46Z

docs/use-cases/control-motor.md

+
+First, [create a machine](/cloud/machines/#add-a-new-machine) if you haven't yet.
+
+Then, [add a board component](/components/board/), such as a [Raspberry Pi board](/components/board/pi/).


hmmm do you think you could actually get this done in 60 seconds. We may need to adjust this. We may also need to add a requirements section that says you need to have a board with a supported OS installed and a motor connected.

I think 2-3 minutes is more realistic, especially if adding a new machine is a step. I also like the idea of adding a requirements section. I can adjust this to 2 minutes and test it out a bit on an actual motor. What do you think?

docs/use-cases/control-motor.md

npentrel · 2024-06-18T22:18:57Z

docs/use-cases/control-motor.md

+
+You can use [the Viam mobile app](/fleet/#the-viam-mobile-app) to control your motor's speed and direction directly from your smart device.
+
+{{<gif webm_src="/fleet/mobile-app-control.webm" mp4_src="/fleet/mobile-app-control.mp4" alt="Using the control interface under the locations tab on the Viam mobile app" max-width="300px">}}


I'm not sure whether this will be confusing given people only have a motor configured :/ . Maybe we crop this?

I recorded a new gif, but I could also just crop this one!

npentrel · 2024-06-20T16:19:18Z

docs/tutorials/get-started/quickstarts/control-motor.md

We want to add a new quickstarts section in the get-started section here: https://docs-test.viam.dev/3036/get-started/, so this should be under tutorials

this should've said this should not be under tutorials - sorry. I'll move this and then merge

npentrel · 2024-06-20T16:26:28Z

layouts/shortcodes/expand.html

+  </summary>
+  <div class="expand-content">
+    {{- if (findRE "(gif|mp4)_src" .Inner) -}}
+    <div class="media-wrapper">


what does this media-wrapper do here?

Thanks for catching this, it was a leftover class from attempting to figure out an issue with the 'alignright'" class.

There was a rendering issue with the tabs shortcode and the gif overlapping, but using the 'clear' attribute worked. This will be gone in the next commit!

npentrel · 2024-06-20T16:27:26Z

layouts/shortcodes/expand.html

+    </span>
+  </summary>
+  <div class="expand-content">
+    {{- if (findRE "(gif|mp4)_src" .Inner) -}}


and what does this do? It looks for gifs and mp4s and if so wraps it with safeHTML and otherwise uses markdownify? Is that needed for edgecases?

Yes! The purpose of this conditional was to ensure that the content of the HTML element 'details' is processed as markdown when it's not a gif or mp4.

Prior to adding the markdownify conditional, the hyperlinks would not render as hyperlinks within the new shortcode. Since the original shortcode uses 'div' in the original shortcode, this didn't need to be explicitly written as it seems that 'div' takes care of this for us.

docs/tutorials/get-started/quickstarts/control-motor.md

npentrel · 2024-06-20T16:30:57Z

docs/tutorials/get-started/quickstarts/control-motor.md

+
+    # motor-1
+    motor_1 = Motor.from_robot(machine, "motor-1")
+    motor_1_return_value = await motor_1.is_moving()


can you use a different method here? This will not move the motor but just return that it's not moving.

Same for go

npentrel

Ok this looks good - a few small changes, then I think this is ready to test on someone :)

viambot · 2024-06-21T16:52:25Z

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

skyleilani changed the title ~~DOCS-2481: dd how to control motor~~ DOCS-2481: Add motor how to Jun 18, 2024

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

skyleilani marked this pull request as ready for review June 18, 2024 19:18

skyleilani requested a review from npentrel June 18, 2024 19:21

npentrel requested changes Jun 18, 2024

View reviewed changes

npentrel reviewed Jun 20, 2024

View reviewed changes

docs/tutorials/get-started/quickstarts/control-motor.md Outdated Show resolved Hide resolved

npentrel reviewed Jun 20, 2024

View reviewed changes

docs/tutorials/get-started/quickstarts/control-motor.md Outdated Show resolved Hide resolved

npentrel reviewed Jun 20, 2024

View reviewed changes

skyleilani and others added 12 commits June 21, 2024 17:28

add content and shortcode

8b194fd

add to index page

8ee0726

remove typo

1c93393

fix typo

536e253

address feedback

c32f1e7

fix whitepsace and typo

d48a927

remove webm files from assets/get-started

06eeb0c

update expand shortcode with new shortcode

649f506

Update docs/tutorials/get-started/quickstarts/control-motor.md

54f59e3

Update docs/tutorials/get-started/quickstarts/control-motor.md

1a78eb3

Move content and minor fixups

4f53ddf

Fix styling

ed0712f

npentrel force-pushed the DOCS-2481-Add-how-to-control-motor branch from 8c42988 to ed0712f Compare June 21, 2024 16:28

Fix linting

9415a94

npentrel force-pushed the DOCS-2481-Add-how-to-control-motor branch from 5091591 to b73a2e2 Compare June 21, 2024 16:35

Update get-started landing page

abd4c02

npentrel force-pushed the DOCS-2481-Add-how-to-control-motor branch from b73a2e2 to abd4c02 Compare June 21, 2024 16:37

Fix broken link

5e3f381

npentrel merged commit 7eba729 into viamrobotics:main Jun 21, 2024
8 of 9 checks passed

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

DOCS-2481: Add motor how to #3036

DOCS-2481: Add motor how to #3036

skyleilani commented Jun 18, 2024 •

edited

Loading

viambot commented Jun 18, 2024 •

edited

Loading

npentrel left a comment

npentrel Jun 18, 2024

skyleilani Jun 19, 2024 •

edited

Loading

npentrel Jun 20, 2024

skyleilani Jun 20, 2024

npentrel Jun 20, 2024

npentrel Jun 18, 2024

skyleilani Jun 18, 2024 •

edited

Loading

npentrel Jun 18, 2024

skyleilani Jun 19, 2024

npentrel Jun 20, 2024

npentrel Jun 21, 2024

npentrel Jun 20, 2024

skyleilani Jun 20, 2024

npentrel Jun 20, 2024

skyleilani Jun 20, 2024

npentrel Jun 20, 2024

npentrel Jun 20, 2024

npentrel left a comment

viambot commented Jun 21, 2024


		First, [create a machine](/cloud/machines/#add-a-new-machine) if you haven't yet.

		Then, [add a board component](/components/board/), such as a [Raspberry Pi board](/components/board/pi/).


		You can use [the Viam mobile app](/fleet/#the-viam-mobile-app) to control your motor's speed and direction directly from your smart device.

		{{<gif webm_src="/fleet/mobile-app-control.webm" mp4_src="/fleet/mobile-app-control.mp4" alt="Using the control interface under the locations tab on the Viam mobile app" max-width="300px">}}

DOCS-2481: Add motor how to #3036

DOCS-2481: Add motor how to #3036

Conversation

skyleilani commented Jun 18, 2024 • edited Loading

viambot commented Jun 18, 2024 • edited Loading

npentrel left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

skyleilani Jun 19, 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

skyleilani Jun 18, 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

Choose a reason for hiding this comment

npentrel left a comment

Choose a reason for hiding this comment

viambot commented Jun 21, 2024

skyleilani commented Jun 18, 2024 •

edited

Loading

viambot commented Jun 18, 2024 •

edited

Loading

skyleilani Jun 19, 2024 •

edited

Loading

skyleilani Jun 18, 2024 •

edited

Loading